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PREFACE 



This manual is one of the set of manuals that document the Multiprogramming Executive Operating 
System (MPE-IV). The manual plan on the next page indicates the position of this manual (shaded 
block) in the overall set. 

This manual describes the set of intrinsics available with the MPE Operating System and tells you how 
to communicate with MPE programmatically. In addition, capabilities available to users with special 
capability-class attributes are described. 

An introduction to MPE intrinsics is presented in Section I. The specifications for all intrinsics, in 
alphabetical order, are contained in Section II. Functional descriptions of the intrinsics, including 
those intrinsics for which special capabilities are required, are presented in the remaining sections, 
as follows: 



Section III Interprocess Communication and Circular Files 

Section IV Utility Functions of MPE Intrinsics. 

Section V Device Characteristics. 

Section VI Resource Management. 

Section VII Process-Handling Capability. 

Section VIII Data Segment Management Capability. 

Section IX Privileged Mode Capability. 

Section X Accessing and Altering Files 
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CONVENTIONS USED IN THIS MANUAL 



The normal conventions (braces, brackets, etc.) used for MPE Commands do not apply to MPE 
intrinsic calls. 

See page 2-1 for a description of the conventions used in this manual. 
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In the MPE Operating System, individual programming operations are handled by sets of code 
known as procedures. These procedures are coded in SPL (Systems Programming Language for the 
MPE Operating System) and are defined by a procedure declaration consisting of 

• A procedure head, containing the procedure name and type, parameter definitions, and 
other information about the procedure. 

• A procedure body, containing executable statements and data declarations local to this 
procedure. 

As part of their function, several procedures also return values to the processes that invoke them. 

NOTE 

A process is the basic executable entity in MPE. A process is 
not a program itself, but the unique execution of a program 
by a particular user at a particular time. 



Each procedure is invoked by a corresponding procedure call. When a procedure call is encountered 
in a program, control is transferred to the procedure. The procedure runs until an exit is 
encountered, at which time control returns to the statement following the procedure call. 

In addition to the procedures provided by the operating system, MPE allows the user to write 
special-purpose procedures in SPL. To distinguish MPE system procedures (which are always 
available to the user, either directly or indirectly) from any other procedures, the term intrinsic is 
applied to MPE system procedures. Similarly, the term intrinsic call is used to denote the procedure 
call that references an MPE system procedure. 

PURPOSES AND USES OF MPE INTRINSICS 

With MPE intrinsics, it is possible to 

• Access and alter files. Files can be opened, read, written on, updated, and otherwise 
manipulated using intrinsics. 

• Request various utility operations, such as: 

Listing date, time, and accounting information. 
Determining job status. 
Determining device status. 
Obtaining devicefile information. 
Transmitting messages. 
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1-1 



• 



• 



Inserting comments in command stream. 

Requesting ASCII/binary number conversion. 

Reading input from job/session input device. 

Writing output to job/session list device. 

Obtaining system timer information. 

Determining the user's access mode and attributes. 

Searching arrays and formatting parameters. 

Executing MPE commands programmatically. 

Enabling and disabling error traps. 

Requesting program break, termination, or abort. 

Changing the lengths of the user-managed area (DL to DB) and stack area (Z to DL) and 

altering DL to DB and Z to DL register offsets. 

Managing interprocess communication through the job control word. 

Changing terminal speed and echo mode. 

Access and manage a system resource such as an input/output device, file, program, 
subroutine, procedure, code segment, or the data stack such that no other program may 
use the resource simultaneously. 

In addition, users with certain optional capabilities (see OPTIONAL CAPABILITIES, 
page 1-12) may use intrinsics to 

Create and delete processes. 

Activate and suspend processes. 

Send information (mail) between processes. 

Change the scheduling of processes. 

Obtain information about existing processes. 

Create and access extra data segments. 

Lock as many resources as desired simultaneously. 

To help you determine what you can accomplish with MPE intrinsics, a summary is presented in 
table 1-1. Table 1-1 lists each intrinsic, and the capability necessary to use it. 

INTRINSIC CALLS 

Intrinsic calls invoke MPE system procedures which are requested programmatically (that is, from 
within a user program). In SPL programs (see CALLING INTRINSINCS FROM SPL, below), you 
write the intrinsic calls explicitly. In FORTRAN, COBOL, BASIC, and RPG programs, for most 
general applications, the compiler for that language generates any necessary intrinsic calls 
automatically — they are invisible to you. It is possible, however, to call intrinsics directly from 
these languages (see CALLING INTRINSICS FROM OTHER LANGUAGES, page 1-10). 

All MPE intrinsics are treated as external procedures by user programs. External linkages from user 
programs to intrinsics are satisfied when the user programs are segmented (at PREPARATION time) 
and allocated residence in virtual memory (at RUN time). See the MPE Segmenter Reference 
Manual for a discussion of segments, segmentation, and allocation. 

CALLING INTRINSICS FROM SPL 

Before an intrinsic can be called from an SPL program, it must be declared at the beginning of the 
program, following all data declarations, like any other SPL procedure. This could be done by 
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Table 1-1. Summary of MPE Intrinsics 



INTRINSIC 
NAME 


i : 

PURPOSE 


1 

CAPABILITY REQUIRED 


ACCEPT 


Accepts (and completes) a request received by the 
preceding GET intrinsic call. (Used only with DS/3000.) 


Standard 


ACTIVATE 


Activates a process. 


Process Handling 


ADJUSTUSLF 


Adjusts directory space in a USL file. 


Standard 


ALTDSEG 


Alters the size of an extra data segment. 


Data Segment Management 


ARITRAP 


Enables or disables internal interrupt signals from all 
hardware arithmetic traps. 


Standard 


ASCI! 


Converts a number from binary to ASCII code. 


Standard 


BINARY 


Converts a number from ASCII to binary code. 


Standard 


CALENDAR 


Returns the calendar date. 


Standard 


CAUSEBREAK 


Requests a session break. 


Standard 


CLEANUSL 


Deletes inactive entries from USL file. 


Standard 


CLOCK 


Returns the actual time. 


Standard 


CLOSELOG 


Closes access to the logging facility. 


LG Capability 


COMMAND 


Executes an MPE command programmatically. 


Standard 


CREATE 


Creates a process. 


Process Handling 


CREATEPROCESS 


Provides ability to assign $STDIN and $STDLIST 
to any file 


Process Handling 


CTRANSLATE 


Converts a string of characters from EBCDIC to ASCII 
or from ASCII to EBCDIC. 


Standard 


D ASCII 


Converts a value from double-word binary to ASCII code. 


Standard 


DATELINE 


Returns date and time information. 


Standard 


DBINARY 


Converts a number from ASCII code to a double-word 
binary value. 


Standard 


DEBUG 


Calls the DEBUG facility. 


Standard 


DLSIZE 


Changes size of DL to DB area. 


Standard 


DMOVIN 


Copies block from data segment to stack. 


Data Segment Management 


DMOVOUT 


Copies block from stack to data segment. 


Data Segment Management 


EXPANDUSLF 


Changes length of a USL file. 


Standard 
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Table 1-1. Summary of MPE Intrinsics (Continued) 



INTRINSIC 
NAME 


PURPOSE 


CAPABILITY REQUIRED 


FATHER 


Requests Process Identification Number (PIN) of 
father process. 


Process Handling 


FCARD 


Drives the HP 7260A Optical Mark Reader. 


Standard 


FCHECK 


Requests details about file input/output errors. 


Standard 


FCLOSE 


Closes a file. 


Standard 


FCONTROL 


Performs control operations on a file or terminal device. 


Standard 


FDELETE 


Deactivates a RIO record. 


Standard 


FDEVICECONTROL 


Adds control directives to a spooled device file. 


Standard 


FERRMSG 


Returns message corresponding to FCHECK error 
number. 


Standard 


FFILEINFO 


Provides access to file information. 


Standard 


FGETINFO 


Requests access and status information about a file. 


Standard 


FINDJCW 


Searches Job Control Word (JCW) table for specified 
JCW. 


Standard 


FLOCK 


Dynamically locks a file. 


Standard 


FMTCALENDAR 


Formats calendar date. 


Standard 


FMTCLOCK 


Formats time of day. 


Standard 


FMTDATE 


Formats calendar date and time of day. 


Standard 


FOPEN 


Opens a file. 


Standard 


FPOINT 


Resets the logical record pointer for a sequential disc 
file. 


Standard 


FREAD 


Reads a logical record from a sequential file (on any 
device) to the user's data stack. 


Standard 


FREADBACKWARD 


Reads a logical record beginning at a point prior to 
the current record printer 


Standard 


FREADDIR 


Reads a logical record from a direct access file to the 
user's data stack. 


Standard 


FREADLABEL 


Reads a user file label. 


Standard 


FREADSEEK 


Prepares, in advance, for reading from a direct-access 
file. 


Standard 


FREEDSEG 


Releases an extra data segment. 


Data Segment Management 
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Table 1-1. Summary of MPE Intrinsics (Continued) 



INTRINSIC 
NAME 



FREELOCRIN 



F RE LATE 



FRENAME 



FSETMODE 



FSPACE 



FUNLOCK 



FUPDATE 



FWRITE 



FWRITEDIR 



FWRITELABEL 



GENMESSAGE 



GET 



GETDSEG 



GETJCW 



GETLOCRIN 



GETORIGIN 



GETPRIORITY 



GETPRIVMODE 



PURPOSE 



Frees all local Resource Identification Numbers (RlN's} 
from allocation to a job. 



Determines if a file pair is interactive or duplicative. 



GETPROCID 



GETPROCINFO 



GETUSERMODE 



Renames a disc file. 



Activates or de-activates file-access modes. 



Spaces forward or backward on a file. 



Dynamically unlocks a file. 



Updates a logical record residing in a disc file. 



Writes a logical record from the user's stack to a sequen- 
tial file (on any device). 



Writes a logical record from the user's stack to a direct- 
access disc file. 



Writes a user file label. 



Accesses MPE message system. 



Receives the next request from a remote master program. 
(Used only with DS/3000.) 



Creates an extra data segment. 



Fetches contents of system job control word (JCW). 



Acquires local RlN's. 



INITUSLF 



IODONTWAIT 



Determines source of process activation call. 



Changes the priority of a process. 



Dynamically enters privileged mode. 



Requests PIN of a son process. 



Requests status information about a father or son 
process. 



Dynamically returns to non-privileged mode. 



Initializes a USL file to the empty state. 



Initiates completion operations for an I/O request. 



CAPABILITY REQUIRED 



Standard 



Standard 



Standard 



Standard 



Standard 



Standard 



Standard 



Standard 



Standard 



Standard 



Standard 



Standard 



Data Segment Management 



Standard 



Standard 



Process Handling 



Process Handling 



Privileged Mode 



Process Handling 



Process Handling 



Privileged Mode 



Standard 



Privileged Mode 



1-5 



Table 1-1. Summary of MPE Intrinsics (Continued) 



INTRINSIC 
NAME 


PURPOSE 


CAPABILITY REQUIRED 


IOWAIT 


Initiates completion operations for an I/O request. 


Privileged Mode 


KILL 


Deletes a process. 


Pocess Handling 


LOADPROC 


Dynamically loads a library procedure. 


Standard 


LOCKGLORIN 


Locks a global RIN. 


Standard 


LOCKLOCRIN 


Locks a local RIN. 


Standard 


LOCRINOWNER 


Identifies process locking a local RIN. 


Standard 


MAIL 


Tests mailbox status. 


Process Handling 


MYCOMMAND 


Parses (delineates and defines parameters) for user- 
supplied command image. 


Standard 


OPEN LOG 


Provides access to a logging facility. 


LG Capability 


PAUSE 


Suspends calling process for a specified number of 
seconds. 


Standard 


PCHECK 


Returns an integer code specifying the completion status 
of the most recently executed DS/3000. (Used only with 
DS/3000.) 


Standard 


PCLOSE 


Terminates program-to-program communication with a 
remote slave program. (Used only with DS/3000.) 


Standard 


PCONTROL 


Exchanges tag fields with a remote slave program. (Used 
only with DS/3000.) 


Standard 


POPEN 


Initiates program-to-program communication with a 
remote slave program. (Used only with DS/3000.) 


Standard 


PREAD 


Requests a block of data from a remote slave program. 
(Used only with DS/3000.) 


Standard 


PRINT 


Prints character string on job/session list device. 


Standard 


PRINTFILEINFO 


Prints file information display. 


Standard 


PRINTOP 


Prints a character string on the Operator's Console. 


Standard 


PRINTOPREPLY 


Prints a character string on the Operator's Console and 
solicits a reply. 


Standard 


PROCTIME 


Returns a process' accumulated central processor time. 


Standard 


PTAPE 


Accepts input from paper tapes which do not contain 
X-OFF control characters. 


Standard 
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INTRINSIC 
NAME 



PUTJCW 



PWRITE 



QUIT 



QUITPROG 



READ 



READX 



RECEIVEMAIL 



REJECT 



RESETCONTROL 



RESETDUMP 



SEARCH 



SENDMAIL 



SETDUMP 



SETJCW 



STACKDUMP 



SUSPEND 



SWITCHDB 



TERMINATE 



TIMER 



UNLOADPROC 



UNLOADGLORIN 



Table 1-1. Summary of MPE Intrinsics (Continued) 



PURPOSE 



Puts value of a given JCW in JCW table. 



Sends a block of data to a remote slave program. 



Aborts a process. 



Aborts the user process structure. 



Reads an ASCII string from the job/session input device 
($STDIN). 



UNLOCKLOCRIN 



WHO 



WRITELOG 



XARITRAP 



XCONTRAP 



XLIBTRAP 



Reads an ASCli string from the job/session input device 
(SSTDINX). 



Receives mail from another process. 



Rejects the request received by the preceding GET 
intrinsic call. (Used only with DS/3000.) 



Resets terminal to accept CONTROL Y signal. 



Disables the abort stack analysis facility. 



Searches an array for a specified entry or name. 



Sends mail to another process. 



Enables the abort stack analysis facility. 



Sets the value of the system job control word (JCW). 



Dumps selected parts of stack to file. 



Suspends a process. 



Switches DB register pointer. 



Terminates a process. 



Returns job or session timer bit count. 



Dynamically unloads a library procedure. 



Unlocks a global RIN. 



Unlocks a local RIN. 



Returns user attributes. 
Writes a record to a logging file. 



Arms or disarms the software arithmetic trap. 



Arms or disarms the CONTROL-Y trap. 



Arms or disarms the library trap. 



CAPABILITY REQUIRED 



Standard 



Standard 



Standard 



Standard 



Standard 



Standard 



Process Handling 



Standard 



Standard 



Standard 



Standard 



Process Handling 



Standard 



Standard 



Standard 



Process Handling 



Privileged Mode 



Standard 



Standard 



Standard 



Standard 



Standard 



LG Capability 



Standard 



Standard 



Standard 



1-7 



INTRINSIC 
NAME 



XSYSTRAP 



ZSIZE 



Table 1-1. Summary of MPE Intrinsics (Continued) 



PURPOSE 



Arms or disarms the system trap. 



Changes size of Z to DB area. 



CAPABILITY REQUIRED 



Standard 



Standard 



writing the entire intrinsic declaration but, because some intrinsic declarations are rather long, you 
can save time by declaring intrinsics with the INTRINSIC declaration statement. 

The format of the INTRINSIC declaration statement is 

INTRINSIC intrinsicname, intrinsicname, . . . ,intrinsicname; 

In the intrinsicname list, you name all intrinsics that you intend to call within your program. When 
more than one intrinsic is named, the names must be separated by commas. For example, to use the 
INTRINSIC declaration statement to declare the FOPEN, FREAD, FWRITE, and FCLOSE 
intrinsics, you could write 

INTRINSIC FOPEN,FREAD,FWRITE,FCLOSE; 

Regardless of whether you declare an intrinsic as a procedure or in an INTRINSIC declaration 
statement, you must know the number and type of parameters which the intrinsic uses in order to 
call it correctly. Parameters can be passed to a procedure (intrinsic) either by value or by reference. 
When a parameter is passed by reference (the default case), its address in the caller's data area is 
made available to the called procedure. If the variable is changed by the called procedure, the 
storage in the caller's data area is updated. When a parameter is passed by value, the called 
procedure receives a local (private) copy of the actual data value. If the called procedure changes 
this private copy, the corresponding variable in the calling routine remains unchanged. 

You call an intrinsic in your program exactly as you would any SPL procedure: that is, you write 
the intrinsic name, followed by a parameter list enclosed in parentheses. These parameters must 
follow the positional format shown in each intrinsic description (Section II). Parameters must be 
separated from each other by commas. For example, a call to the FREAD intrinsic could be written 
as 

FREAD(FN,TAR,TC); 

where the filenum, target, and tcount parameters (see Section II, page 2-82) are represented by FN, 
TAR, and TC, respectively. If numeric values are to be specified for the filenum and tcount 
parameters (which are VALUE parameters), the following call could be used: 

FREAD(3,TAR,-80); 

If the OPTION VARIABLE notation appears in the intrinsic description shown in Section II, some 
of the intrinsic parameters are optional. Since all intrinsic parameters are positional, however, you 
must indicate a missing parameter within a parameter list by omitting the parameter itself but 
retaining the preceding and following commas. For example, if the second parameter is missing 

FOPEN(FILENAME„3); 

If the first parameter is omitted from a list, this is indicated by following the left parenthesis with a 
comma. If one or more parameters are omitted from the end of a list, however, this is indicated by 
simply writing the terminating right parenthesis after the last parameter included. 
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NOTE 



In some intrinsic calls, input parameters are passed to the 
intrinsic as words whose individual bits or fields of bits 
signify certain functions or options. In cases where some of 
the bits within a word are described in this manual as 
"reserved for MPE", you are advised to set such bits to zero. 
This will help insure the compatibility of your current 
program with future releases of MPE. 

In cases where output parameters are passed by an intrinsic 
to words referenced by a calling program, bits within such 
words that are described as "reserved for MPE" are set to 
zero unless otherwise noted in the discussion of the particular 
parameter. 

To call an intrinsic from an SPL program, follow the steps listed below: 

1. Refer to the intrinsic description in Section II to determine the parameter types and their 
positions in the parameter list. 

2. Declare the variables or array names to be passed as parameters by type at the beginning 
of the program. 

3. Include the name of the intrinsic in an INTRINSIC declaration statement. 

4. Issue the intrinsic call at the appropriate place in your program. 

For example, refer to Section II, page 2-147 for a description of the PRINTOP intrinsic. This 
intrinsic is shown as 

A IV IV 

YRmTOP(message,length,control); 

The bold face italics shown for message, length, and control signify that these are required 
parameters. (Optional parameters are signified by regular italics.) 

. . . „ T , xtt „„ f„~,rfj, Q «ri s>nntml Hpnnt.fi loeical armv. integer by 

The superscripts A, iv, ana iv uver ukoou,^, ^.<. s ^.», <~ = 

value, and integer by value, respectively. 

The array name to be used as the message parameter must be declared as an array at the beginning 
of the program. If variable names are used for the length and control parameters, ^ey ^u-* ~e 
declared as type integer at the beginning of the program. 

Figure 1-1 shows the intrinsic PRINTOP being called from an SPL program after being declared 
with the INTRINSIC declaration statement. Note that MESSAGE is declared as an array and the 
variables LENGTH and CONTROL are declared as type integer. 

Figure 1-2 shows the same intrinsic being called with numeric values, instead of symbolic identifiers, 
being specified for the parameters length and control. 
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PAGE 0001 


HP32100A.06.0 <C) COPYRIGHT HEWLETT-PACKARD COMPANY 


1976 


00001000 


00000 





SCONTROL USLINIT 




00002000 


00000 









00003000 


00000 





<< USING THE INTRINSIC DECLARATION STATEMENT 


>> 


00004000 


00000 









00005000 


00000 





BEGIN 




00006000 


00000 


I 


ARRAY MESSAGE(0:9):="MESSAGE TO OPERATOR 




00007000 


00012 


1 


INTEGER LENGTH, CONTROL; 




00008000 


00012 


1 


I MTRI NSI C PHI NTOP; 




00009000 


00012 


1 






00010000 


00012 


1 


LENGTH:=10; 




00011000 


00002 


1 


CONTROL :=X60; 




00012000 
00013000 


00004 
00010 


! 
1 


PFIJITQS'tf'Miree.ARir.T swctu. rnuTom i. 






00014000 


00010 


1 


END. 




PRIMARY 


DB STORAGE= 


S003; SECONDARY DB STORAGE=S000 1 2 




NO. ERRORS=000; 




NO. WARNINGS=000 




PROCESSOR TIME= 


0:00 


J00; ELAPSED TIME=0: 01 : 23 





Figure 1-1. CaUing the PRINTOP Intrinsic from SPL 
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00001000 
00002000 
00003000 
00004000 
00005000 
00006000 
00007000 
00008000 
00009000 
00010000 
0001 1000 
PRIMARY 



00000 
00000 
00000 
00000 
00000 
00000 
00012 
00012 
00012 
00004 
00004 
DB 



SCONTROL USLINIT 

<< USING NUMERIC VALUES AS PARAMETERS >> 

BEGIN 

ARRAY MESSAGE<0:9):="MESSAGE TO OPERATOR 
INTRINSIC PRINTOP J 

PRINTOPCMESSAGE, 10,X60>> 



END. 



STORAGE=%001; 
NO. ERRORS=000; 
PROCESSOR TIME=0:00:00; 



SECONDARY DB 
NO. WARNINGS= 
ELAPSED TIME= 



STORAGE=X00012 

000 

0:00: 53 



Figure 1-2. Using Numeric Values as Parameters in an Intrinsic Call 
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CALLING INTRINSICS FROM OTHER LANGUAGES 

For most applications in FORTRAN, COBOL, BASIC, and RPG programs, the compiler for the 
specific language generates any necessary intrinsic calls automatically. It is possible, however, to call 
intrinsics, or other library procedures, from these languages. The procedures for calling intrinsics 
from these languages are described in the applicable language reference manuals. 

INTRINSIC CALL ERRORS 

Some intrinsics alter the condition code returned to FORTRAN and SPL programs through two 
bits (6 and 7) in the Status register. These two bits have four states which are defined as follows: 

00 Defined as CCG, or condition code greater than. 

01 Defined as CCL, or condition code less than. 

10 Defined as CCE, or condition code equal. 

11 Undefined. 

Since bits 6 and 7 of the Status register are affected by many instructions, you should check for 
condition codes immediately upon return from an intrinsic (see figure 1-3). A condition code is 
always CCG, CCL, or CCE, and has the general meaning indicated below. The specific meaning, of 
course, depends upon the intrinsic called and these meanings are described in Section II. 

Condition Code State General Meaning 

CCE Condition code equal. This generally indicates that the request 

was granted, 

CCG Condition code greater. A special condition occurred but may 

not have affected the execution of the request. (For example, 
the request was executed, but default values were assumed as 
intrinsic call parameters.) 

CCL Condition code less. The request was not granted, but the error 

condition may be recoverable. Beyond this condition code, 
some intrinsics return further error information in the program 
through their return values. 

Two types of errors may occur when an intrinsic is executed. The first, denoted by the CCG or CCL 
condition codes, is generally recoverable (control returns to the calling program) and is known as a 
condition code error. The second type is an abort error, which occurs when a calling program passes 
illegal parameters to an intrinsic, or does not have the capability demanded by the intrinsic. 
Intrinsic (system) traps are handled by a special procedure designed for that purpose. Normally, if 
an intrinsic causes the trap to be invoked, the system trap handler aborts the user program. You 
may, however, specify a procedure to be used instead of the default system trap handler and try to 
recover from such errors. If the program is aborted in a batch job, MPE removes the job from the 
system (unless a : CONTINUE command, defined in the MPE Commands Reference Manual, 
precedes the error). If the program is aborted in an interactive session, MPE returns control to the 
terminal. Abort-error messages are described in Section X. 
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00002000 
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00006000 


00000 


1 


00007000 


00012 


1 


00008000 
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00009000 


00011 


1 


00010000 


0001 1 


1 


00011000 


0001 1 


1 


00012000 


00004 


1 


00013000 


00004 


1 


00014000 


00005 


i 


00015000 


00006 


1 


00016000 


00006 


1 


00017000 


00006 


1 


00018000 


00012 


1 


00019000 


00013 


1 


00020000 


00013 


1 


00021000 


00013 


1 


00022000 


00017 


1 


00023000 


00017 


1 


00024000 


00017 


1 


PRIMARY 


DB STORAGE= 


NO. ERRORS=000; 




PROCESSOR TIME= 


0:00 



SCONTROL USLINIT 

<< CONDITION CODE CHECKS >> 

BEGIN 

ARRAY MESSAGEC0:9):="MESSAGE TO OPERATOR "; 
ARRAY OKBUFC0:9):="MESSAGF TRANSMITTED "; 
ARRAY ERRBUFC0:8):="I/O ERROR OCCURRED"; 
INTRINSIC PRINTOP, PRINT; 

PRINTOPCMESSAGE, 10, X60); 

IF » firEK GOTO r iKi 
IF < THEN GOTO ERR; 

OK: 

PRINTCOKBUF, I0,X60>; 
GOTO stop; 

ERR: 

PRINTCERRBUF, 9^X60); 

STOP: 

END. 
X003; SECONDARY DB STORAGE=%00035 

NO. WARNlNGS=000 
:0i; ELAPSED TIME=0: 01 : 55 



Figure 1-3. Condition Code Checks 



NOTE 

Whenever an intrinsic is invoked by a process and the DB 
register is pointing to the DB area in the user's stack, a 
bounds check takes place to insure that all parameters in the 
intrinsic call reference addresses that lie between the DL and 
S addresses in the stack (prior to the intrinsic call). If an 
address outside of these boundaries is referenced, an abort 
error occurs. 

When an intrinsic is invoked by a process running in the 
privileged mode, and the DB register points to a data segment 
other than the user's stack segment (split stack), the results 
depend on the particular intrinsic. Most intrinsics abort 
immediately in this case. Others, indicated in Section II, are 
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allowed to execute following a bounds check that insures 
that ail parameters in the intrinsic call reference addresses 
that lie within the data segment. Any boundary violation 
results in an abort error. Any additional special actions taken 
by a particular intrinsic are described in the discussion of that 
intrinsic in Section II. 

Figure 1-3 illustrates the use of condition code checks in a program. If the condition code is CCE 
(meaning that the request was granted), the program displays "MESSAGE TRANSMITTED". For a 
CCL condition code, the message "I/O ERROR OCCURRED" is displayed and the program 
terminates normally. 

OPTIONAL CAPABILITIES 

Users with the Standard MPE Capability can perform most functions available through the 
operating system. There are some functions, however, which can only be performed by users with 
certain optional capabilities assigned to them when the Accounts, Groups, and Users are created by 
the System Manager. 

The Process-Handling Optional Capability allows you to programmatically 

» Create and delete processes. 

• Activate and suspend processes. 

• Send mail between processes. 

• Change the scheduling of processes. 

• Obtain information about existing processes. 

The Process-Handling Optional Capability is described in Section VII. 

The Data-Segment Management Optional Capability allows you to create and access extra data 
segments from processes during a job or session. This capability is described in Section VIII. 

Multiple Resource Identification Number Optional Capability. Users having standard MPE 
capability can lock only one global or local Resource Identification Number (RIN) at a time. The 
Multiple Resource Identification Number Optional Capability, however, allows you to lock as many 
RIN's as desired simultaneously, without checking by the operating system. The Multiple RIN 
Optional Capability is described in Section VI. 

The Privileged Mode Optional Capability allows you to access all areas of the system and use all 
features of the hardware. This capability allows you to access all system tables and invoke all system 
instructions, including those in the privileged central processor unit instruction set. In short, this 
capability allows you to use the computer on the same terms as the operating system itself. The 
Privileged Mode Optional Capability is described in Section IX. 
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IMPORTANT NOTE 

The normal checks and limitations that apply to the standard 
users in MPE are bypassed in privileged mode. It is possible 
for a privileged mode program to destroy file integrity, includ- 
ing the MPE operating system software itself . Hewlett-Packard 
will investigate and attempt to resolve problems resulting 
from the use of privileged mode code. This service, which is 
not provided under the standard Service Contract, is available 
on a time and materials billing basis. However, Hewlett- 
Packard will not support, correct, or attend to any modifica- 
tion of the MPE operating system software. 



The User Logging Optional Capability provides a flexible transaction logging capability which 
enables you to journalize additions and modifications to your data bases and subsystem files. User 
logging permits you to journalize on two mediums: tape and disc. If the data base is lost, the logging 
tape or disc file can be used to recover the lost transactions. 
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This section contains descriptions of all intrinsics, arranged alphabetically. Each intrinsic description 
includes the following information: 

• The intrinsic name, a brief summary of its function, and the number of the intrinsic. (The 
number is only significant for error diagnosis. See the Error Messages and Recovery 
Manual.) 

• The complete intrinsic call description highlighted by being enclosed in a shaded box. The 
intrinsic call descriptions are in the format shown below for the ACTIVATE intrmsic: 



IV LV 0-V 
ACTIVATE(/wi,suspt: 

"eq-ir-d parameters, such as pin. are shown in bold face italics; optional parameters 
(susp) are shown in regular italics. Superscripts are used to describe the types of 
parameters and whether they must be passed by value, instead of by reference (the 
default case). See Section I, page 1-8 for a discussion of passing parameters by value and 
by reference. The superscripts have the following meanings: 



BA 


Byte array 


BP 


Byte pointer 


D 


Double 


DA 


Double array 


DV 


Double by value 


I 


Integer 


IA 


Integer array 


IV 


Integer by value 


L 


Logical 



LA Logical array 
LV Logical by value 
O-P Option privileged 
O-V Option variable 
R Real 

In addition to the superscripts shown over the parameters, the superscript O-V is shown 
for some intrinsics to denote option variable. Option variable means that the intrinsic 
contains optional parameters. Additionally, O-P is shown for those intrinsics which can be 
called only when running in privileged mode. The ACTIVATE intrinsic shown, for ex- 
ample contains two parameters: pin, which is a required integer parameter that must be 
passed by value; and susp, an optional logical parameter that, if included in the intrinsic 
i, , t i ^ p a k„ waino AHHitfnnallv. the intrinsic is option variable, meaning that 

some parameters are optional. 
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FUNCTIONAL RETURN: For those intrinsics which return a value to the calling 
program (type procedures), the return is described. If the intrinsic is not a type 
procedure, this portion of the description is omitted. The intrinsic call description format 
for type intrinsics is as shown below for the READ intrinsic: 






The READ intrinsic returns the positive length of the input actually read. This value is 
returned to an integer variable. In the intrinsic call description, a word, representing what 
is returned, is shown in italics (as is length, above) to denote that the intrinsic is a type 
procedure. The type (integer, double, etc.) is signified by a superscript above the 
descriptive word. Thus, 



I LA IV 

length : =READimessage,expectedr } ; 



is an integer procedure, message is a required logical array, and expectedl is a required 
integer parameter which must be passed by value. 

NOTE 

:= means "is assigned" or "is replaced by." 

PARAMETERS: All parameters are described. In the intrinsic call description, required 
parameters are shown in bold face italics and optional parameters are shown in regular 
italics. Elsewhere in this manual, this distinction is not shown for required and optional 
parameters and all parameters are shown in regular italics. 

CONDITION CODES: Condition codes are included for each intrinsic. 
SPECIAL CONSIDERATION: 

Required Capability. When you run a program file, the program file's capability 
(established at PREPARATION time) is checked against the capability of the group 
in which the file resides. If the file's capability does not exceed the capability of the 
group, the program executes. Additional capability checking, however, is done if the 
program calls an intrinsic. Some intrinsics require that the program file have 
sufficient capability to call them. If an intrinsic requires a special capability, it will 
be noted in the discussion of that intrinsic. 

NOTE 

The optional capabilities are discussed in Section I, page 1-13. 
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.onw Stack Operations. During normal operation, the DB register points to the user 
process' stack. Some operations with extra data segments require that DB be set to 
the base of the extra data segment while DL and all other data registers remain 
associated with the stack. When a process is operating in this mode it is said to have 
a split stack. Several of the MPE intrinsics deal with DB in this manner and you 
need not be concerned with the mechanics of the operation because while the stack 
is "split" only system code is executing. It is possible, however, if you are a privileged 
user, to force your process to operate in split-stack mode explicitly by calling the 
SWITCHDB intrinsic. 



IMPORTANT NOTE 

The normal checks and limitations that apply to the standard 
users in MPE are bypassed in privileged mode. It is possible 
for a privileged mode program to destroy file integrity, includ- 
ing the MPE operating system software itself. Hewlett-Packard 
will investigate and attempt to resolve problems resulting 
from the use of privileged mode code. This service, which is 
not provided under the standard Service Contract, is available 
on a time and materials billing basis. However, Hewlett- 
facKara will not suppuii/, Currc^u, <->* du»ea w «~ ~-^ — »" — *-« 
tion of the MPE operating system software. 

If you do this, you must recognize that some of the normal callable intrinsics may 
not be called when DB does not point to the stack. Such intrinsics, if called by a 
privileged process in split stack mode, can result in system failures. If you are a 
normal user, you need not concern yourself with this restriction and you may assume 
in all the intrinsics described in this section that unless it is otherwise stated, an 
intrinsic will not operate in split stack mode. 

The SPECIAL CONSIDERATIONS portion of the description is omitted unless the 
intrinsic operates in split stack mode, a special optional capability is required, or the 
intrinsic requires a privileged call. Therefore, unless otherwise stated: 

The intrinsic does not operate in split stack mode. 
The intrinsic requires only standard capabilities. 
The intrinsic does not require a privileged call. 

TEXT DISCUSSION: This references the page in this manual where usage of the intrinsic 
is discussed. 
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ACCEPT 



Accepts (and completes) a request received by 
the preceding GET intrinsic call and returns 
an optional tag field back to a remote master 
program. 



1A IA IV 
ACCEPTOR, target,tcou tit )\ 

See the DS/3000 Reference Manual (32190-90001) for a discussion of this intrinsic. 
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ACTIVATE 



Activates a process. INTRINSIC NUMBER 104 



TV LV e~v 
ACTIVATE{p/»,susp); 

After a process has been created, it must be activated in order to run. Once activated, the process 
runs until it is suspended or deleted. A newly-created process can only be activated by its father. A 
process that has been suspended (with the SUSPEND intrinsic, see page 2-172) can be reactivated by 
its father or any of its sons, as specified in the susp parameter of the ACTIVATE and SUSPEND 
intrinsics. 

The operating system guarantees that there will be no process switching (to some other process) 
between activation of the called process and suspension of the calling process. 

The ACTIVATE intrinsic aborts the calling process (and possibly the entire job/session) if: 

1. The group in which the program file resides does not have the Process- Handling Capa- 
bility, and the program was not prepared with Process -Handling Capability. 

2. The required parameter pin is omitted. 

3. A request to activate the father would result in activation of a job or session main process 
or a system process. 

PARAMETERS 

pin integer by value (required) 

Process Identification Number (PIN). An integer specifying the PIN for 
the son or father process to be activated. The PIN number to activate a 
father process is always zero. The called process must always be 
expecting an activation from the caller as noted in the discussion of the 
SUSPEND (see page 2-172) and CREATE (see page 2-19) intrinsics. 

susp logical by value (optional) 

A word that specifies: 

The calling process is to be suspended while the called process is 
activated and commences execution. 

or 

The called process is activated by the operating system but does not 
commence execution immediately. Instead, control is returned to the 
calling process which will continue execution. 

When susp is omitted or is zero, the calling process remains active. 
When susp is specified, the calling process is suspended. The 14th and 
15th bits of susp specify the anticipated source of the call that later will 
reactivate the calling process. 

Bit (15:1) — If on, the process expects to be activated by its father. 

Bit (14:1) — If on, the process expects to be activated by one of its 

sons. 

If both bits are on, the suspended process can be activated by either the 

father or sons. 
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Bits (0:14) — Reserved for MPE. Should be set to zero. 
Default: Calling process remains active. 

CONDITION CODES 

CCE Request granted. Called process is activated. The calling process is 

suspended if susp was specified. 

CCG The called process already is active. The calling process is suspended if 

susp was specified. 

CCL Request denied, because the called process was not expecting activation 

by this calling process; an illegal pin parameter was specified; or the 
susp parameter was specified improperly. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 
Process-Handling Capability required. 

TEXT DISCUSSION 

Page 8-10 
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ADJUSTUSLF 



Adjusts directory space in a vau me. "> - «.-*-"«- - 1 * ^-*- °° 



I IV IV 

ermu m : = AmVSTUSLFiwtftmmsecords ); 

The ADJUSTUSLF intrinsic moves the start of the information block forward or backward on a 
user subprogram library (USL) file, thereby increasing or decreasing, respectively, the space 
available for the file directory block. Note that this does not change the overall length of the file. 
This intrinsic is intended for programmers writing compilers. See the MPE Segmenter Reference 
Manual for a discussion of USL's, the ADJUSTUSLF intrinsic, information blocks, and directory 
blocks. 

FUNCTIONAL RETURN 

This intrinsic returns an error number if an error occurs. If no error occurs, no value is returned. 

PARAMETERS 

uslfnum integer by value (required) 

A word supplying the file number of the USL file (as returned by 

FOPEN). 

records integer by value (required) 

A word supplying a signed record count. If records is greater than zero, 
the information block is moved toward the end-of-file in the USL file, 
increasing the space available for the directory block and decreasing the 
space available for the information block. If records is less than zero, 
the information block is moved toward the start of the USL file, 
decreasing the directory-block space and increasing the information- 
block space. 

CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CQL Request denied. One of the following error numbers is returned. 

Error Number Meaning 

The file specified by uslfnum was empty, 

or an unexpected end-of-file was encoun- 
tered when reading the old uslfnum, or an 
unexpected end-of-file was 
when writing on the new uslfnum. 
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Error Number 
1 



Meaning 

Unexpected input/output error occurred. 
This can occur on the old uslfnum or the 
new uslfnum to which the intrinsic is 
copying the information. 

Your request attempted to exceed the 
maximum file directory size (32,768 
words). 

Insufficient space was available in the USL 
file information block. 



TEXT DISCUSSION 

MPE Segmenter Reference Manual. 
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ALTDSEG 



Alters the size of an extra data segment. INTRINSIC NUMBER 134 



LV IV . I 
ALTDHEG{indexjmsize ) : 

The ALTDSEG intrinsic alters the current size of an extra data segment. ALTDSEG can be used to 
reduce the storage required by the segment when it is moved into main memory, then used again to 
expand storage as required, thus allowing more efficient use of memory. 

Expansion and contraction is accomplished in even multiples of 4, which are rounded up. For 
example, 

Present Segment Size (Words) Change Value (Words) New Segment Size (Words) 

-3 128 

_4 124 

+1 132 

+3 132 

+4 132 

NOTE 

Sufficient virtual space is allocated by the system when a 
data segment is created through GETDSEG to accommodate 
the original length of the data segment. This virtual space is 
allocated in increments of pages where the number of words 
per page is set when the system is configured (typically 512 
words/page). For example, creation of a data segment with a 
length of 600 words would result in two virtual pages being 
allocated for the data segment (space for 1024 words). 

In no case may ALTDSEG increase the size of a data segment 
to exceed the virtual space originally allocated through 
GETDSEG. 

PARAMETERS 

index logical by value (required) 

A word containing the logical index of the extra data segment, obtained 
from the GETDSEG call. 



128 
128 
128 
128 
128 



inc 



integer by value (required) 

The value, in words, by which the data segment is to be changed. A 
positive integer value requests an increase, and a negative integer value 
requests a decrease. 

size integer (required) 

A word to which is returned the new size of the data segment after 
incrementing or decrementing occurs. 
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CONDITION CODES 

CCE Request granted. 

CCG Request not fully granted. An illegal decrement, requesting a new total 

segment size of zero or less, or an illegal increment, requesting a new 
size greater than the virtual space originally assigned by GETDSEG, 
was attempted. In the first case, the current size remains in effect. In 
the second case, the size of the virtual space is granted and this size is 
returned through the size parameter. 

CCL Request denied because an illegal index parameter was specified. 

SPECIAL CONSIDERATIONS 

Data-Segment Management Capability required. 

TEXT DISCUSSION 

Page 8-16 
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ARITRAP 

Enables or disables all hardware arithmetic traps. INTRINSIC NUMBER 51 

LV 
ARITRAP<s/a/<>); 

The interrupts listed below are collectively called the arithmetic user traps. 

When a user process begins execution, all internal arithmetic user traps are enabled. That is, if an 
arithmetic error occurs in the user process, it is aborted in the trap mechanism. The various 
interrupts which can occur are: 

Integer overflow. 
Floating point overflow. 
Floating point underflow. 
Integer divide by zero. 
Floating point divide by zero. 
Double precision overflow. 
Double precision underflow. 
Douuic precision ^ivi^e uy zero. 
Decimal overflow. 
Invalid ASCII digit. 
Invalid decimal digit. 
Invalid source word count. 
Invalid decimal operand length. 
• Decimal divide by zero. 

The traps may be collectively enabled/disabled with the ARITRAP intrinsic call. 

The ARITRAP intrinsic always clears the overflow indicator located in the caller's status word. 

PARAMETERS 

state logical by value (required) 

A -mnvA cY\amf\Tina roVio+Vior all tranc «re» tn hp pnahled nr disabled. 

If state is TRUE (bit 15 = 1), all traps are enabled. 

If state is FALSE (bit 15 = 0), all traps are disabled. 

Bits through 14 are reserved for MPE and should be set to zero. 

CONDITION CODES 

CCE Request granted. The arithmetic traps were originally disabled. 

CCG Request granted. The arithmetic traps were originally enabled. 

CCL Not returned by this intrinsic. 

TEXT DISCUSSION 

Page 4-30. 
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ASCII 



INTRINSIC NUMBER 63 



Converts a one-word binary number to a numeric ASCII string. 



I LV IV BA 

numchar:~A$CU(wrd,ba$e.$tring); 



Any 16-bit binary number can be converted to a different base and represented as a numeric 
character ASCII string by using the ASCII intrinsic call. 

FUNCTIONAL RETURN 

This intrinsic returns the number of characters in the resulting string. 

PARAMETERS 



word 



base 



string 



logical by value (required) 

The number to be converted to an ASCII string. 

integer by value (required) 

An integer indicating octal or decimal conversion. 

8 = octal 

10 = decimal (left justified) 

-10 = decimal (right justified) 

If any other number is entered in this parameter, the intrinsic causes 

the user process to abort. 

byte array (required) 

A byte array into which the converted value is placed. This array must 
be long enough to contain the result. No result, however, exceeds six 
characters. For octal conversion (base = 8), six characters, including 
leading zeros, are always returned in string, showing the octal 
representation of word. In octal conversions, the length returned by 
ASCII is the number of significant (right-justified) characters in string 
(excluding leading zeros). If word = 0, the length (numchar) returned 
by ASCII is 1. 

For decimal conversions, word is considered as a 16-bit, 2's comple- 
ment integer ranging from -32768 to +32767. If the value of word is 
negative, the first byte of string contains a minus sign. If word = 0, only 
one zero character is returned in string. The length (numchar) returned 
by ASCII is the total number of characters in string ( including the 
sign). If word = 0, the length returned by ASCII is 1. 

For decimal left-justified conversions (base = 10), leading zeros are 
removed and the numeric ASCII result is left justified in string. 

For decimal right-justified conversions (base = -10), the result is right 
justified in string. 
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BEGINLOG 



INTRINSIC NUMBER 211 



Marks the beginning of user logging transaction. 



■ .. D LA I I I 

BBOWi/K; [index, date, ■<."?. timde. flntnf). 



The BEGINLOG instrinsic posts a special record to the user logging file to mark the beginning of a 
logical transaction in the log file. When BEGINLOG is used, the logging memory buffer is flushed 
to ensure that the record gets to the logging file. BEGINLOG can be used also to post data to the 
logging file by using the data parameter. This function of BEGINLOG performs the same procedure 
as the WRITELOG intrinsic. 



PARAMETERS 



data 



array (required) 

An array in which the actual information to be logged is passed. A log 
record contains 128 words of which 119 words are available to the user. 
Because of this, the most efficient use of log file space is a multiple of 
119 words. 



len 



index 



integer (required) 

The length of the data in data. A positive count indicates words, and a 
negative count indicates bytes. If the length is greater than 119 words, 
the information in data will be divided into two or more physical 
log records. 

double (required) 

The parameter returned from OPENLOG that identifies the users 

access to the logging system. 



status 



integer (required) 

An integer that the logging system uses to return error information to 

the user. Zero indicates OK status. 



mode 



integer (required) 

An integer which specifies whether you want your process impeded 

by the logging process if the logging buffer is full. If it is not possible 

to log the transaction and the mode is set to nowait, the BEGINLOG 

intrinsic will return an indication in the status word that the request 

was not completed. Mode zero indicates wait; rnoue one muicaues 

nowait. 



CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 

None. 
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INTRINSIC NUMBER 62 Converts a number from an ASCII string to a binary word. 

BA IV 
binegv:=BV8AK¥{string,length); 

FUNCTIONAL RETURN 

This intrinsic returns the binary equivalent of the numeric string. 

PARAMETERS 

string byte array (required) 

Contains the octal or signed decimal number (ASCII characters) to be 
converted. If the character string in this array begins with a percent sign 
(%), it is treated as an octal value. If the string begins with a plus sign, 
minus sign, or a number, it is treated as a decimal value. 

NOTE 
String cannot contain blanks. 

length integer by value (required) 

An integer representing the length (number of bytes) in the byte array 
containing the ASCII-coded value. If the value of length is 0, the 
intrinsic returns to the calling process. If the value of length is less 
than 0, the intrinsic causes the user process to abort. 

CONDITION CODES 

CCE Successful conversion. A one-word binary value is returned to the user's 

process. 

CCG A word overflow, possibly resulting from too many characters (string 

number too large), occurred in the word (bineqv) returned. 

CCL An illegal character was encountered in the byte array specified by 

string. For example, the digits 8 or 9 specified in an octal value. 

TEXT DISCUSSION 

Page 4-13. 
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CALENDAR 



Returns the calendar date. 



INTRINSIC NUMBER 43 



dutc:-=CAl,ENDAK.; 



FUNCTIONAL RETURN 

This intrinsic returns the calendar date in the format 



Bits 



6 7 



15 



Year of Century 



Day of Year 



CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Page 4-44, 
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CAUSEBREAK 

INTRINSIC NUMBER 56 Places a session in break mode. 



Using the CAUSEBREAK intrinsic is the programmatic equivalent to using the BREAK key in a 
session. Execution of the process can be resumed where the interruption occurred by entering the 
command 

: RESUME 

CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because the intrinsic was not called from an interactive 

session. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 
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CLEANUSL 



Deletes inactive entries trom usl, me 

1 JY BA 

fUmum -t'i EANDSL (wtymmjaawmeK 

FUNCTIONAL RETURN 

CLEANUSL deletes all inactive entries from currently managed USL files and returns the new file 
number If an error occurs, the error number is returned instead of the new file number. (See Table 
10-13 CLEANUSL Error Messages) The condition code, therefore, must be tested immediately on 
return' from the intrinsic. Unpredictable results occur if an error number is used as a file number. 

NOTE 

CLEANUSL requires at least 3000 words of available stack 
space to execute. 

PARAMETERS 

uslfiium integer by value (required) 

A word identifier which supplies the file number of the file. 

filename byte array (required) 

The name to be given to the cleaned file. The array must end with a 
blank, but it can be all blanks. If it's all blanks it purges the inactive 
entries. 



CONDITION CODES 

Cce Request granted. The new file number is returned. 

CCG Not returned by this intrinsic. 

CCL Request denied. (See Table 10-13, CLEANUSL Error Messages) 

TEXT DISCUSSION 



None 
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INTRINSIC NUMBER 44 



Returns the time of day. 



fime;*=CLOCK; 



FUNCTIONAL RETURN 

This intrinsic returns the actual time (wall time), as monitored by the system timer, as a double 
word. The first word contains the hour of the day and the minute of the hour, the second word 
contains seconds and tenths of seconds as follows: 



BitsO 



15 



Hour of Day 



Seconds 



Minute of Hour 



Tenths of Seconds 



Wordl 
Word 2 



CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Page 4-44. 
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CLOSELOG 



Closes access to the logging facility. 



INTRINSIC NUMBER 212 



D I I 
L0SELO }>i- c* <m fa m •<•? . 

The CLOSELOG intrinsic closes access to the logging facility. 



PARAMETERS 

index 
mode 



status 



double (required) 

The parameter returned from OPENLOG that identifies your access to 

the logging facility. 

integer (required) 

An integer which you use to indicate whether or not your process 
should be suspended if your request for service cannot be completed 
immediately. Enter a zero if you want to wait for service; enter a one if 
you do not want to wait. 

integer (required) 

An integer which indicates logging system errors to you. (See table 

E-12, User Logging Error Messages.) 



CONDITION CODES 

The condition code remains unchanged. 



TEXT DISCUSSION 



Page 10-93 
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COMMAND 



INTRINSIC NUMBER 68 



Executes an MPE command programmatically. 



' ' BA. 1 ■■ 1 . 

COMM AND(co mintage, error jrnrm ) \ 



NOTE 



User-defined commands may not be used. 



PARAMETERS 



comimage 



error 



byte array (required) 

Contains an ASCII string consisting of a command and parameters ter- 
minated by a carriage return. The carriage return character must be the 
last character of the command string. No prompt character, however, 
should be included in this string. The comimage array may be altered 
by the COMMAND intrinsic (for example, characters in it may be shift- 
ed from lowercase to uppercase), but will be returned in a form that 
can be resubmitted to this intrinsic without adjustment. 

integer (required) 

A word to which any error code set by the command is returned. This 

is the same error code that would appear on a job /session list device if 

the command was part of an input stream, i.e., command interpreter 

error code not file system error code. If no error occurs, error returns 

zero. 



parm 



integer (required) 

A word to which the number (index) of the erroneous parameter is 
returned. If no parameters are in error, parm returns zero. If there are 
errors, parm may be zero or some positive integer. In the case where an 
error refers to a file system problem, parm is the file system error code. 



CONDITION CODES 



CCE 
CCG 



Request granted. 

An executor-dependent error, such as an erroneous parameter, pre- 
vented execution of the command. The error parameter contains the 
numeric error code. 



CCL 



Request denied. The command was an undefined command. 



TEXT DISCUSSION 

Page 4-9 
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V^A^ClKCb a. ^i. 



INTRINSIC NUMBER 100 



■-BA, 



I IV LV IV IV IV 



tj'Ui wnt. | 



asi 



Any running process, if it has the Process-Handling Capability, can request the creation of a son 
process by issuing the CREATE intrinsic call. The CREATE intrinsic loads the program to be run by 
the new process into virtual memory, creates the new process as the son of the calling process, 
initializes its data stack, schedules the process, and returns the new Process Identification Number 
(PIN) to the requesting process. 

The creating process is aborted if: 

1. Request was rejected because of illegal parameters; a PIN of zero is returned. Specifically, 
this occurs: 

• If progname is illegal. 

• If entryname is illegal. 

• If stacksize is less than 512 (decimal) and is not -1. (Note that if -1 is specified, the 
default value is taken.) 

• If dlsize is less than and is not -1. 

• If maxdata is less than or equal to 0, and is not -1. 

• If (dlsize + globsize + stacksize + 128) exceeds maxdata. Note that dlsize may have 
been modified to satisfy condition 2 under CCG. The globsize value is the sum of 
the primary DB plus the secondary DB values (the total DB given at program 
nrfinaration time bv the program map (PMAP)). 

• If (dlsize + globsize + stacksize + 128) exceeds the maximum stacksize defined 
during system configuration. Note that dlsize may have been modified to satisfy 

ti - c\ j r*nr* 

condition & unuei v^-aj. 

• If (maxdata + 90) exceeds 32768, where maxdata is either the value passed as a 
parameter or a value re-computed by the Loader under condition 1 of CCG. 

2. The program file does not have the Process-Handling Optional Capability. 

3. An illegal value (a non-existent subqueue) was specified for the priorityclass parameter. 

4. A required parameter (progname or pin) is omitted. 



5. A reference parameter was not within the required range. 
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PARAMETERS 

progname 



entryname 



pin 



param 



flags 



byte array (required) 

Contains a string, terminated by a blank, specifying the name, and 
optionally, the account and group (filereference format, see Section III, 
page 3-8) of the file containing the program to be run. 

byte array (optional) 

Contains a string, terminated by a blank, specifying the entry point 

(label) in the program where execution is to begin when the process is 

activated. The primary entry point in the program can be specified by 

setting the array equal to a blank character alone. 

Default: The primary entry point is used. 

integer (required) 

A word in which the PIN of the new process is returned to the 
requesting process. This PIN is used in other intrinsics to reference the 
new process. The PIN can range from 1 to 255. If an error is detected, a 
PIN of zero is returned to the requesting process. 

integer by value (optional) 

A word used to transfer control information to the new process. Any 

instruction in the outer block of code in the new process can access this 

information in location Q-4. 

Default: Word is filled with zeros. 

logical by value (optional) 

A word whose bits, if on, specify the loading options: 

NOTE 

Bit groups are denoted using the standard SPL notation. Thus 
bit (15:1) indicates bit 15, bits (10:3) indicates bits 10, 11, 
and 12. 

Bit (15:1) -ACTIVE bit. If on, MPE reactivates the calling process 
(father) when the new process terminates. If off, the 
calling process is not activated at that time. 
Default: Off. 

Bit (14:1) -LOADMAP bit. If on, a listing of the allocated (loaded) 
program is produced on the job/session list device. This 
map shows the Code Segment Table (CST) entries used by 
the new process. If off, no map is produced. 
Default: Off. 

Bit (13:1) -DEBUG bit. If on, a call to DEBUG is made at the first 
executable instruction of the new process. If off, the 
breakpoint is not set. This bit is ignored if the user is 
non-privileged and the new process requires privileged 
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mode. It also is ignored if the user does not have read/write 
access to the program file of the new process. 
Default: Off. 

Bit (12:1) — NOPRIV bit. If on, the program is loaded in non-privileged 
mode. If this bit is off, the program is loaded in the mode 
specified when the program file was prepared. 
Default: Off. 

Bits (10:2) — LIBSEARCH bits. These bits denote the order in which 
libraries are to be searched for the program: 

£ 00 — System Library. 

p 01 — Account Public Library, followed by System Library. 
(j- 10 — Group Library, followed by Account Public Library, 
followed by System Library. 
Default: 00. 

Bit (9:1) — NOCB bit. If on, file system control blocks are established 
in an extra data segment. If off, control blocks may be 
established in the Process Control Block Extension (PCBX) 
area. 
Default: Off. 

NOTE 

This bit should be set on if you are using a large stack. 

Bits (7:2) — Reserved for MPE. Should be set to zero. 

Bits (5:2) — STACKDUMP bits. These bits control the enabling/ 
disabling of the mechanism by which the stack is dumped 
in the event of an abort: 

00 — Enables only if enabled at father level. 

01 — Enables unconditionally = 

10 — Same as 00. 

11 — Disables unconditionally for new process. 
Default: 00. 

Bit (4:1) — Reserved for MPE. Should be set to zero. 

NOTE 

The following bits (0:4) are used only when the bit pair (5:2) 
is 01. Otherwise, these bits are ignored. 

iSlt (ci:!) -- ULi tO Vqjl UlL 11 un, LUc purtdUil ui me auu;n. uum j-»jj w 

QI is dumped. If off, this portion of the stack is not 

dumped. 

Default: Off. 
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Bit (2:1) — QI to S bit. If on, the portion of the stack from QI to S is 
dumped. If off, this portion of the stack is not dumped. 
Default: Off. 

Bit (1:1) -Q-63 to S bit. If on, the portion of the stack from Q-63 to 
S is dumped. If off, this portion of the stack is not 
dumped. 
Default: Off. 

Bit (0:1) - ASCII DUMP bit. If on, the dump is interpreted in ASCII, 
in addition to the octal dump. If off, ASCII interpreting is 
not given. 
Default: Off. 

Default: Default values as noted are taken. 



stacksize 



integer by value (optional) 

An integer ( Z — Q) denoting the number of words assigned to the local 

stack area bounded by the initial Q and Z registers. 

Default: The same as that specified in the program file. 



dlsize 



integer by value (optional) 

An integer (DB — DL) denoting the number of words in the 
user-managed stack area bounded by the DL and DB registers. 
Default: The same as that specified in the program file. 



max data 



integer by value (optional) 

The maximum size allowed for the process' stack (Z — DL) area in 

words. When specified, this value overrides the one established at 

program-preparation time. 

Default: If not specified, and not specified in program file either, MPE 

assumes stack will remain same size. 



priorityclass 



logical by value (optional) 

A string of two ASCII characters describing the priority class in which 

the new process is scheduled. This may be all, as discussed under 

Rescheduling Processes (see Section VII, page 7-13) for users with 

Process-Handling Capability, or CS, DS, and ES for users without the 

Process-Handling Capability. 

Default: The same as the priority of the calling process. 



rank 



integer by value (optional) 

This parameter is used only for compatibility with previous versions of 

the MPE Operating system. It is ignored for all users. 



NOTE 

For the stacksize, dlsize, and maxdata parameters, a value of 
-1 indicates that the MPE Segmenter is to assign default 
values. Specifying -1 is equivalent to omitting the parameter. 
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CONDITION CODES 

CCE Request granted. The new process is created. 

CCG Request granted. The maxdata and/or dlsize parameters given were 

illegal, but other values were used, as follows: 

1. If the maxdata specified exceeds that maximum Z — DL allowed by 
the configuration, the configuration maximum value is assigned. 

2. If (dlsize + 100) modulo 128 is not zero, then dlsize is rounded 
upward so that (dlsize + 100) modulo 128 = 0. 

CCL Request denied because the progname or entryname specified does not 

exist. 

SPECIAL CONSIDERATIONS 

Process-Handling Capability required. 

TEXT DISCUSSION 

Page 7-3. 
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INTRINSIC NUMBER 101 Provides the ability to assign 

$STDLIST and $STDIN to any file. 

1 1 BA IA LA O-V 

CUEATEPROCESS(error,pin,prognameJtemnumsjtems): < u 

.. , , .. -, .. (- _ r '*-- . 

The CREATERPROCESS Intrinsic allows you to assign the system defined files, $STDIN and 
$STDLIST, to any file at process creation time. You are not limited to system defined defaults. 
Note that Process -Handling capability is required to call this intrinsic, and that it may not be 
called in split stack mode. If the intrinsic is called with the error parameter omitted, an invalid 
address for parameter error is returned. In split stack mode, the calling process will be aborted. 

PARAMETERS 

error integer (required) . r-\ 

An integer indicating success or failure type. (See Table E-14.) Q- ±- ~ ' 

pin integer (required) 

An integer in which the PIN of the newly created process is returned. 
If there is an error in creating the new process, i.e., parameter error > 
a zero is returned. 

progname byte array (required) 

A byte array containing a string terminated by any non-alphanvmeric 
character other than a period or a slash which specifies the name of the 
program file to be run by the new process. 

itemnums integer array (optional) 

An array containing the item numbers (in any order) of the options you 
want to use in creating a new process. This array must contain a zero as 
its last element to indicate the end of the option list. (See Figure 2-0). 

items logical array (optional) 

An array containing the items (in the same order as the item numbers 
in itemnums), to be used in creating the new process. (See Figure 2-0.) 

CONDITION CODES 

CCE No error. 

CCL Unsuccessful. 

CCG Successful. Error numbers preceded by a minus sign (-) indicate a 

warning only. (See Table E-14.) 

SPECIAL CONSIDERATIONS V<H E-i^ 

Process-Handling capability required. 

TEXT DISCUSSION 

None. 
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The item numbers in the array itemnums indicate the options to be applied in creating the new process. The 
corresponding items in the array items give the information necessary for each option to be used. 



Itemnumber 



4 

5 
6 

7 



10 



11 



12 
NOTES 



Item 

A pointer to a byte array containing the name of the entry point in the program where the 
new process is to begin execution. The name is specified as a string of characters terminated 
by a blank. 

An integer containing a parameter to be passed to the new process (accessed through Q-4 
of the outer block). 

A logical value containing the load option flags to be used in loading the program file for the 
new process. This parameter has the same definition as the flags parameter of the CREATE 
intrinsic. 

An integer specifying the initial stack size (Q - Z). 

An integer specifying the initial DLsize (DL-DB) for the new process. 

An integer specifying the maximum stack size (DL-Z) for the new process (i.e. MAXDATA). 

A string of 2 ASCII characters specifying the priority class in which the new process is to be 
scheduled. {"CS", "DS", or "ES".) 

a pointer to a byte array containing the definition of a file to be used as $STDIN for the 
new process. (See description below). 

A pointer to a byte array containing the definition of a file to be used as $STDLIST for the 
new process (see description below). 

A logical value indicating suspension and anticipated source of re-activation. Specification 
of this parameter causes the newly created process to be ACTIVATEd automatically upon 
creation completion. The meanings of the individual bit fields of this parameter are the same 
as those of the susp parameter of the ACTIVATE intrinsic. 

A pointer to a byte array containing a string of information to be passed to the new process. 
The length of the string is specified with item number 12. 

An integer specifying the length in bytes of the string specified with item number 1 1 . 



„ _^ -i: i „i i_f_..i* <tcxniM or>ri <tQTni l<?T uuill hp ii5A(i in creatina the new 
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process. These defaults are the current $STDIN and SSTDLIST files for the creating (father) process. 

Item number 8 indicates that the corresponding item in the item array is the address of a byte array which 
contain.: thp definition of the file to be used as $STDIN for the new process. This byte array must contain an 
ASCII string (terminated by a carriage return) which is the right hand side of a file equation specifying the file 
to be used as $STDIN (i.e. everything after the ":FILE formaldesignator=" portion of the file equation). 

Item number 9 indicates that the corresponding item in the item array is the address of a byte array which 
contains the definition of the file to be used as SSTDLIST for the new process. This array is defined as above 
for$STDIN. 

Item numbers 1 1 and 12 indicate that a string is to be passed to the new process. The string will be placed just 
after the global area of the new process's stack. A DB relative byte P°jnter tt> the string in the new process s 
stack will be placed at Q-5 of the stack (where Q is the initial value of the O-register at activation time,, an_ 
the length of the string in bytes will be placed at Q-6. If no string is specified to be passed to the new process, 
Q-5 and Q-6 will both contain 0. 
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Figure 2-0. Item Number and Corresponding Items 
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INTRINSIC NUMBER 61 



Converts a string of characters from EBCDIC to 
ASCII, ASCII to EBCDIC, EBCDIK to JIS (katakana), 

or JIS to EBCDIK. 



IV BA BA 

CHB.AKSLATE(code.imtring,ou 



IV BA 0-V 



The CTRANSLATE intrinsic is used for character code translating, whether between the standard 
computer character codes or with a user defined code. It permits you to obtain character code con- 
versions within programs of your own design. In the code parameter of CTRANSLATE, the follow- 
ing values specify the translation table to be used: 

PARAMETERS 



code 



instring 



outstring 



stringlength 



table 



integer by value (required) 

An integer identifying a specific translation to be used as follows: 

= The user supplied table specified in the parameter, table. 

1 = EBCDIC to ASCII. 

2 = ASCII to EBCDIC. 

3 = Reserved for future use. 

4 = Reserved for future use. 

5 = EBCDIK to JIS (katakana data). 

6 = JIS to EBCDIK. 

byte array (required) 

The string of characters to be translated. 

byte array (optional) 

A byte array to which is returned the translated character string. If 
outstring is not specified, all translation will occur within instring. 
The parameters instring and outstring may specify the same array. 

integer by value (required) 

A positive integer specifying the length (in bytes) of instring. 

byte array (required when code = 0) 

A byte array to be used as the translation table. The contents of table, 
and the order of these contents, define the translation process. The 
length of table may be as large as 256 bytes, but it needs to be only as 
large as the largest numeric value of any source byte in instring. The 
table is constructed such that each byte in the table corresponds to a 
byte value in the source string to be translated; for example, the fifth 
byte in the table gives the code to be substituted for source bytes 
whose value is 4. 
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NDITION CODES 



CCE Request granted. Translation performed successfully, 

CCG Not returned by this intrinsic. 

CCL Request denied because an error occurred. 

TEXT DISCUSSION 

Page 4-13 
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INTRINSIC NUMBER 75 



Converts a two-word binary number (double word) 
to a numeric ASCII string. 



IP 



1)V IV BA 



numchar.**DASCll(dword,base,stringy, 



A 32-bit double-word binary number can be converted to a different base and represented as a 
numeric character ASCII string by issuing the DASCII intrinsic call. 

FUNCTIONAL RETURN 

This intrinsic returns the number of characters in the resulting string. 

PARAMETERS 



dword 



double by value (required) 

A double-word value indicating the number to be converted to ASCII 

code. 



base 



string 



integer by value (required) 

An integer indicating octal or decimal conversion. 

8 = octal 

10 = decimal (left justified) 

If any other number is entered in this parameter, the intrinsic causes 
the user process to abort. 

byte array (required) 

The byte array into which the converted value is placed. This array 

must be long enough to contain the result. No result, however, exceeds 

11 characters. 



For octal conversion (base = 8), 11 characters, including leading zeros, 
are always returned in string, showing the octal representation of 
dword. The length (numchar) returned by DASCII is the number of 
significant (right justified) characters in string, excluding leading zeros. 
If dword = 0, the length returned by DASCII is 1. 

For decimal conversions (base = 10), dword is considered as a 32-bit, 
2's complement integer ranging from -2,147,483,648 to 
+2,147,483,647. Leading zeros are removed and the numeric DASCII 
result is left justified in string. If the value of dword is negative, the 
first byte of the string returned contains a minus sign. If dword = 0, 
only one zero character is returned to string. String can contain up to 
11 characters, including the sign. If dword = 0, the length returned by 
DASCII is 1. 
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CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 

Page 4-13. 
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DATELINE 

Returns date and time information. 



BA 

: . DATfiWNE 1 {dm ebufji . : 

PARAMETERS 

datebuf byte array (required) 

A byte array reference, (minimum 27 characters), to which the date 
and time information is returned. 

byte string Fri, May 2 5, 1979, 12:06 PM 

byte index 01234567 89 1011121314151617181920212223242526 
L I I I — I I I I L_l i i i i i i i i il 



CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 

None 
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I 11 II 

c*W:=DBINARY(,$Wi«g.fc//grti ); 

The DBINARY intrinsic performs double-integer ASCII to binary conversion. 

FUNCTIONAL RETURN 

This intrinsic returns the converted double-word binary value to dval. 

PARAMETERS 

string byte array (required) 

Contains the octal or signed decimal number (in ASCII characters) to 
be converted. If the character string in this array begins with a percent 
sign (%), it is treated as an octal representation. If the string begins with 
a plus sign, minus sign, or number, it is treated as a decimal 
rGpr6S6iiu3.uion. 

length integer by value (required) 

An integer representing the length (number of bytes) in the string 
containing the ASCII-coded value. If the value of length is 0, the 
intrinsic returns to the calling process. If the value of length is less 
than 0, the intrinsic causes the user process to abort. 

CONDITION CODES 

CCE Successful conversion. A double-word binary value is returned to the 

program. 

(XG A word overflow, possibly resulting from too many characters (string 

number too large), occurred in the word returned. 

CCL An illegal character was encountered in string. For example, the digits 8 

or 9 specified in an octal value. 

TEXT DISCUSSION 

Page 4-13. 
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INTRINSIC NUMBER 99 Invokes the DEBUG facility. 

DEBUG; 

PARAMETERS 

None. 

CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 

MPE DEBUG/Stack Dump Reference Manual. 
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lands or contracts the area between DL and DB INTRINSIC NUMBER 135 

in multiples of 128 words. 



IV! 






This intrinsic causes the area between DL and DB to be expanded or contracted within the stack 
segment All current information within the area is saved on expansion. If contracting, data in the 
area which is to be contracted is lost. A request for contraction less than the initial DL size of the 
area causes the initial DL size to be granted and an error condition (CCL) to be returned. If the size 
requested causes the stack to exceed the maximum size permitted by the stack area (Z - DL), only 
this maximum is granted. 

All addressing within the DL to DB area is DB relative negative indexing. Therefore, SPL is the only 
language at present, which can access this area for you. If you wish to access this area in SPL, 
please note that the original data is not moved relative to DB on expansion or contraction of the 
area. For example, if a variable is located at DB - 10 before an expansion, it will be at DB - 10 after 
the expansion. 

FUNCTIONAL RETURN 

This intrinsic returns the size actually granted. This value is a negative quantity except on error 
condition CCL when it is possible to have a positive value returned. 

PARAMETERS 



size 



integer by value (required) 

A negative integer representing the new size of the DL to DB area. A 
size of is permitted and resets the DL to DB area to the original value 
assigned when the process was created (initial DL). (This is the only 
way to contract the DL to DB area.) The size granted will be an absolute 
value which is rounded up so that the distance between the beginning 
of the segment to DB is a multiple of 128 words. 

CONDITION CODES 

CCE Request granted. The value returned is at least as large as the value 

requested. 

CCG Requested size exceeded maximum limit allowed. The maximum limit 

allowable is granted and its size is returned. 

CCL i. An illegal size parameter was specified. The size parameter was a 

positive integer or the negative size requested was smaller than the 
original DL to DB area. The original area size assigned when the 
stack segment was created is granted and this size is returned as a 
negative value. 
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The data segment is a FROZEN stack segment which cannot be 
changed until the system UNFREEZES it. The area remains 
unchanged. The value returned is a positive integer size of the area 
and denotes this special error conditions. 



TEXT DISCUSSION 

Page 4-22. 
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Copies data from data segment to stack. 



INTRINSIC NUMBER 132 



I V IV IV J, A 



A process can copy data from an extra data segment into the stack by issuing the DMOVIN intrinsic 
call. A bounds check is performed by the intrinsic on both the extra data segment and the stack to 
insure that the data is taken from within the data segment boundaries and moved to an area within 
the stack boundaries. For example, in the diagram shown below, if you wish to move 4 words from 
locations 422 through 425 of the data segment whose index is 21 to DB + 40 through DB + 43 of 
your stack, the intrinsic call would be 



DMOVIN( 21 ,422,4,ARA( 1 0) ); 

The index is 21 (from GETDSEG, see page 2-111); displacement (disp) within the data segment is 
422; the number of words to move into the stack is 4; and the DB relative location to begin 
transferring the data is the address of ARA(IO). If ARA(IO) is at DB + 40, the end result will be the 
4 words moved to DB + 40 through DB + 43 within the stack, as shown below. 



STACK 



DL 

DB 
ARA(O) 

ARA(1) 










ARA(10)DB+40 


042503 


41 


045501 


42 


047113 


43 


040522 


Q 
S 

z 





DATA SEGMENT 
(GETDSEG INDEX = 21) 



422 
423 
424 
425 



12000 



042503 



045501 



04/n.i 
040522 
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PARAMETERS 

index 
disp 



number 



location 



logical by value (required) 

A word containing the logical index of the extra data segment, obtained 

from a GETDSEG intrinsic call. 

integer by value (required) 

The displacement of the first word in the string to be transferred, from 
the first word in the data segment. This must be an integer value greater 
than or equal to zero. 

integer by value (required) 

The size of the data string to be transferred, in words. This must be an 

integer value greater than or equal to zero. 

logical array (required) 

The array (buffer) in the stack where the data string is to be moved. 



CONDITION CODES 

CCE 
CCG 
CCL 



Request granted. 

Request denied because of bounds-check failure. 

Request denied because of illegal index or number parameter. 



SPECIAL CONSIDERATIONS 

Data-Segment Management Capability required. 

TEXT DISCUSSION 

Page 8-15. 



2-38 



DMOVOUT 



Copies data from stack to extra data segment. 



INTRINSIC NUMBER 133 



LV .. IV \f IV LA 
DMGVQmXmdexJisprMimherJ&emwn); 

The DMOVOUT intrinsic copies data from the stack to an extra data segment. A bounds check is 
initiated to insure that the data is taken from an area within the stack boundaries and moved to an 
area with the extra data segment boundaries. 

In the example shown below,-if you wish to move 4 words from DB + 20 within your stack to the 
data segment whose index is 2 (from a GETDSEG call, see page 2-111), starting at location 201 
within the segment, the intrinsic call could be 



DMOVOUT(2,201,4,ARA(10)); 

The index is 2; the displacement (disp) within the data segment is 201; the number of words to be 
moved to the data segment is 4; and the location of the data within the stack is the address of 
ARA(IO). If ARA(IO) is at DB + 20, the end result is that the 4 words within the Si-ack wu» be 
moved to words 201 through 204 of the data segment, as shown below. 



STACK 



DATA SEGMENT 
(GETDSEG INDEX = 2) 



UL 

DB 




ARA(0) 






AnAUJ 




DB+20 


054517 


21 


052522 


22 


047101 


23 


046505 


Q 
S 

z 










201 


054517 


202 


052522 


203 


047101 


204 


046505 


4096 
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ENDLOG 



INTRINSIC NUMBER 211 



Marks the end of a user logging transaction. 



1J LA I I I 

ENDLOG (index, data, U-n, mode, status)- 



The ENDLOG intrinsic posts a special record to the logging file to mark the end of a logical 
transaction in the logging file. When the record is posted, ENDLOG flushes the user logging memory 
buffer to ensure that the record gets to the logging file. 

The data parameter of the intrinsic can be used to post user data to the log file. This function of 
the procedure is identical to the WRITELOG intrinsic. 



PARAMETERS 



data 



array (required) 

An array in which the actual information to be logged is passed. A log 
record contains 128 words of which 119 words are available to the user. 
Because of this, the most efficient use of log file space is a multiple of 
119 words. 



len 



integer (required) 

The length of the data in data. A positive count indicates words and a 

negative count indicates bytes. If the length is greater than 119 words, 

the information in data will be divided into two or more physical log 

records. 



index 



mode 



status 



double (required) 

The parameter returned 

access to the logging file. 



from OPENLOG that identifies the user's 



integer (required) 

An integer which specifies whether you want your process impeded by 
the logging process if the logging buffer is full. If it is not possible to 
log the transaction and the mode is set to nowait, the ENDLOG intrin- 
sic will return an indication in the status word that the request was not 
completed. Mode zero indicates wait; mode one indicates nowait. 

integer (required) 

A« ;~*4-i,v.*. +k n + +Urt ]r^r*rnv\re ptip+om iicac 4-r\ v£»fiirn awfw infnrmntirtn t.Ci 
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the user. Zero indicates no errors. 



CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 

None. 
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PARAMETERS 

index 
disp 



number 



location 



logical by value (required) 

A word containing the logical index of the extra data segment, obtained 

through a GETDSEG call. 

integer by value (required) 

The displacement, in the extra data segment, of the first word of the 
receiving buffer from the first word in the data segment. This value 
must be an integer greater than or equal to zero. 

integer by value (required) 

The size of the data string to be transferred, in words. This must be an 

integer value greater than or equal to zero. 

logical array (required) 

The array (buffer) in the stack containing the data to be moved. 



CONDITION CODES 

CCE Request granted. 

CCG Request denied because of bounds-check failure. 

CCL Request denied because of illegal index or number parameter. 

SPECIAL CONSIDERATIONS 

Data-Segment Management Capability required. 

TEXT DISCUSSION 

Page 8-15. 
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INTRINSIC NUMBER 84 



I 
filenum: 



JV 



IV 



You can increase or decrease the length of a USL file by calling the EXPANDUSLF intrinsic. 

When this intrinsic is executed, a new USL file is created whose length is records longer or shorter 
than the USL file specified by uslfnum. The old USL file is copied to the new file with the same file 
name, and the old USL file then is deleted. 

FUNCTIONAL RETURN 

This intrinsic returns the new file number. If an error occurs, the error number is returned instead 
of the new file number. The condition code therefore must be tested immediately on return from 
this intrinsic. If an error number were to be used as a file number, unpredictable results would 
occur. 



PARAMETERS 

uslfnum 



records 



integer by value (required) 

A word identifier supplying the file number of the file. 

integer by value (required) 

A signed integer specifying the number of records by which the length 
of the USL file is to be changed. If records is positive, the new USL file 
is longer than the old USL. If records is negative, the new USL file is 
shorter than the old USL. 



CONDITION CODES 

CCE Request granted. The new file number is returned, 

^.^.y. M.-.+ 1-Q+nmorl Ww t.Viis intrinsic. 



ilUU XV. 



CCL 



Request denied. One of the following error numbers is returned. 



Krror iNumDer 




l\.yToQV*lT1tf 



The file specified by uslfnum was empty, 
or an unexpected end-of-file was encoun- 
tered when reading the old uslfnum, or an 
unexpected end-of-file was encountered 
when writing on the new uslfnum. 

TTv,/-vo-vvi~+f"l inniit/nii-t-niit. OTTOI" occurred. 

This can occur on the old uslfnum or the 
new uslfnum to which the intrinsic is 
copying the information. 
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Error Number 

7 

8 



10 



11 



TEXT DISCUSSION 

MPE Segmenter Reference Manual. 



Meaning 

The intrinsic was unable to open the new 
USL file. 

The intrinsic was unable to close (purge) 
the old USL file. 

The intrinsic was unable to close (save) the 
new USL file. 

The intrinsic was unable to close 
$NEWPASS. 

The intrinsic was unable to open 
$OLDPASS. 
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FATHER 

Requests PIN of father process. INTRINSIC NUMBER 109 

pin:=»FATI-IEE; 

A process can determine the Process Identification Number (PIN) of its father by issuing the 
FATHER intrinsic call. 

FUNCTIONAL RETURN 

This intrinsic returns the PIN of the process' father. 

CONDITION CODES 

C CE Request granted. The father is a user process. 

CCG Request granted. The father is a job or session main process. 

CCL Request granted. The father is a system process. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Page 7-14. 
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FCARD 



Drives the HP 7260A Optical Mark Reader (OMR) 



I I IA I I 
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The FCARD intrinsic allows you to control the operation of the 7260A OMR programmatically. 
This is achieved through passing a parameter (recode), corresponding to the function of FCARD 
desired, from your program to FCARD. FCARD returns to the program parameter values which 
indicate the success or the cause of failure of execution, the status of the 7260A, the file number 
of the 7260A/terminal file for which the function has been performed and the number of columns 
read at the completion of a read request. 



PARAMETERS 



recode 



integer (required) 

A positive integer represented as an input or output parameter. As an 

input parameter, recode requests one of the following twelve options 

(functions): 

= Open the reader and the terminal as a file and return to the 

program the filenum through SPL/3000 conventions. 

1 = Read a single card whether in ASCII or in column image format. 

See Section V for descriptions of ASCII and column image read- 
ing formats. 

2 = Select the previously read card by routing the card into the select 

output hopper (providing option 002 of the 7260A is installed). 

3 = Retransmit data from the previously read card. This transmission 

may be performed in ASCII or column image reading formats, 
depending on latest issued FCARD call specifying recode equal to 
11 or 12. 

4 = Temporarily suspend the program awaiting an operator action 

(depress the 7260A "READY" switch). This particular call to 
FCARD will maintain control and will not be completed until the 
operator presses the 7260A "READY" switch. 

10 = Cause the 7260A motor to come to a stop and de-activate MUTE 

for the associated terminal, if muted. When MUTE is activated and 
the 7260A is in its "READY" state, data transmission from the 
computer and from the 7260A to the terminal is disabled. 

11 = Cause the output format of the subsequent read (recode=l) and 

retransmit (recode=3) requests to be performed in the image read- 
ing format. 

In image mode reading, count is returned to the program with the 
number of columns which have been transmitted. 
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12 = Cause the output format of the subsequent read (recode-1) and 

retransmit (recoo'e=3) requests to be performed in the ASCII read- 
ing format. 

In ASCII mode reading, count is returned to the program with the 
number of characters (columns) transmitted. 

13 = Cause the 7260A optional bell to ring (providing option 004 is 

installed). 

17 = Enable the "echo-on" function of the computer. 

18 = Disable the "echo-on" function of the computer. 

20 = Close the reader/terminal file opened with recode=Q. This effec- 
tively completes the program. 

As an output parameter, recode indicates to the program whether a 
call to FCARD has been properly executed. The indication given by 
the value of recode is as described below: 
= Indicates that the request, i.e., the call to FCARD, has been suc- 
cessfully performed. For the following conditions, when output 
recode=0, the specified parameters are significant to the program: 

a. If the request was to open a file (recode=0), then filenum is 
significant. 

b. If the request was either to read (recode=l) or to retransmit 
(recode=3), then bufadr (the first byte may contain status infor- 
mation identical to that contained in the parameter status), 
count, filenum and status are significant. 

c. If the request was to select the previously read card (recode=2), 
then status is significant. 

d. If the request was to perform a temporary suspension of the 
program (recode=A), then status is significant. 

e. For all other requests (recocte=10,ll,12,17,18 and 20), none of 
tne otner paraiiieueis cue aigiuj.ii*uii/. 

1 = Indicates that recode specified in the request was not one of the 
following legal values: 0,1,2,3,4,10,11,12,13,17,18 or 20. 

o _ t„ j:„„+«« 4-U*4- J?n A Dr* Tiroo nnohla +r\ r\r\ari +ht» 79.R0 A /terminal 

pair as a file. This error is not recoverable, thus the program 
should indicate an error and terminate itself. 

4 = Indicates that FCARD has encountered a file read or write error 

while accessing the 7260A. This error is not recoverable, thus the 
program should indicate an error and terminate itself. 

5 = Indicates that FCARD was unable to close the 7260A/terminal 

file. This error is not recoverable, thus the program should indi- 
cate an error and proceed to a normal termination. 
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filenum 



bufadr 



count 



status 



6 = Indicates that a logical end-of -data (: JOB, :EOJ, :EOD and 

:DATA) was encountered while reading data in response to either 
a read or retransmit request. 

7 = Indicates that FCARD has encountered a file error on requests for 

either enabling or disabling the echo function. 

8 = Indicates that FCARD has detected a data dropout condition 

while the 7260A was transmitting. You should request a retrans- 
mission of the data or status (see recode=3). 

integer (required) 

A word identifier supplying the file number of the file associated with 
the reader/terminal file. This file number is returned to the program 
from FCARD with output recode=0. It must be provided to FCARD 
on all requests. 

integer array (required) 

The array to which the record is to be transferred. This parameter 

should be set to 120 words. 

integer (required) 

A positive integer which is returned to the program upon completion of 
a read (recode=l) or a retransmit (recode=3) request indicating the num- 
ber of columns which have been transferred from the 7260A OMR. 

integer (required) 

An integer indicating whether the OMR has successfully performed or 
responded to the read, select, retransmit, or temporary suspend request. 
If status is equal to zero, then the request has been successfully 
performed. If status is not equal to zero, then it contains an octal value 
specifying the OMR condition. The options are: 



OCTAL 22 READY status. Indicates that the OMR READY 
push button has been pressed (recode=4). Would 
also indicate that the OMR is ready but there is no 
data to be retransmitted (recode=3). 

OCTAL 07 Input hopper empty or hopper full status. Can 

either be returned upon a read request (recode=l) 
or upon a retransmit request, if there is no data to 
retransmit (recode=3). 



OCTAL 11 



Pick fail status. Can either be returned upon a read 
request (recode=l) or upon a retransmit request, if 
there is no data to retransmit (recode=3). 
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OCTAL 37 



OCTAL 14 



OCTAL 13 



Not ready status. Can either be returned upon a 
read request (recode=l) or upon a retransmit re- 
quest (recode=3). This status is provided by the 
OMR if the operator has pushed the OMR STOP 
push button or if a lamp has burned out in the 
OMR read head. 

Select successful status. Indicates that the OMR 
has successfully selected the card upon the select 
request {recode=2). 

Select hopper full status. Indicates that the OMR's 
select hopper was full when the select request 
(recode=2) was issued. 



FCARD derives the parameter status by assigning the contents of the 
first byte of bufadr to status, if this byte equals one of the values of 
status given above after a read (recode=l), select (recode=2) or retrans- 
mit (recode=3) request, or if this byte equals octal 22 after a request 
for a temporary suspension of the program (recode=4). 

For more details on the OMR status, refer to the HP 7260A Operating 
and Service Manual (HP Part No. 07260-90001). 



CONDITION CODE 

The condition code remains unchanged. 

TEXT DISCUSSION 

Page 5-28. 
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INTRINSIC NUMBER 10 



Requests details about file input/output errors. 



IV 
>num,i 



i i 



11 



I 0-V 



When a file intrinsic returns a condition code indicating a physical input/output error, additional 
details may be obtained by using the FCHECK intrinsic call. This intrinsic applies to files on any 
device. 

FCHECK accepts zero as a legal filenum parameter value. When zero is specified, the information 
returned in errorcode reflects the status of the last call to FOPEN. When an FOPEN fails, there is 
obviously no file number which can be referenced in filenum. Therefore, when an FOPEN fails, a 
filenum of zero can be used in the FCHECK intrinsic call to obtain the errorcode only. If the tlog, 
blknum, or numrecs parameters are specified, a zero value will be returned to these parameters. If a 
filenum of zero is used for a file which has been previously FOPENed, but not yet FCLOSEd, the 
returned errorcode will be meaningless. 



PARAMETERS 



filenum 



errorcode 



tlog 



blknum 



numrecs 
numrecs 



integer by value (optional) 

A word identifier supplying the file number of the file for which error 
information is to be returned. If omitted, FCHECK assumes you want 
the last FOPEN error. 

integer (optional) 

A word to which is returned an 8-bit code (16 bits for KSAM) specifying 

the type of error that occurred. If the previous operation was successful 

or an EOF is encountered, all 16 bits are set to zero. 

Default: The error code is not returned. 

integer (optional) 

A word to which is returend the transmission log value recorded on the 

last data transfer. This word specifies the number of words actually 

read or written if an input/output error occurred. 

Default: The transmission log value is not returend. 

double (optional) 

The physical record count, if the file is not a spool file; the logical 
record count if it is a spool file. The physical count is the number of 
physical records transferred to or from the file since a) FOPEN, for 
fixed and undefined length record files; b) the last rewind, rewind/ 
unload space forward or backward to tape mark, for variable length 
record files. 

integer (optional) 

A word to which is returned the number of logical records in the bad 

block (blocking factory). 

Default: The number of logical records is not returned. 
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In the 16 bits returned to the word specified by the errorcode parameter, the iow-order eight bits 
contain the error-type code that shows what kind of error occurred. (Non KSAM access.) 

The following codes are returned in errorcode by FCHECK: 
Code 
(Decimal) Meaning 

End of file. 

1 Illegal DB register setting (typically, a request in split -stack mode 
when it is illegal). 

2 Illegal capability. 

3 Parameter omitted in IOWAIT. 
5 DRT number > 255. 

8 Illegal parameter value. 

9 Undefined file type. 

10 Invalid record size. 

11 Invalid block size. 

12 Record number out of range. 

16 More than 255 FOPENs applied against one file. 

17 Magnetic tape runaway (tape is blank). 

18 Device did a power-up reset. 

19 Line printer did a VFC reset. 

20 Invalid operation. 

21 Data parity error. 

22 Software time-out. 

23 End of tape. 

24 Unit not ready. 

25 No write ring on tape. 

26 Transmission error (No defective track table entry is made on foreign 

discs). 

27 Input/output time-out. 

28 Timing error or data overrun. 

. 29 Start input/output (SIO) failure. 

• 30 Unit failure. 

31 End of line (special character terminator). 

32 Software abort of input/output operation. 

33 Data lost. 

34 Unit not on-line. 

35 Data set not ready. 

36 Invalid disc address. 

37 Invalid memory address. 

38 Tape parity error. 

39 Recovered tape error. 

40 Operation inconsistent with access type. 

41 Operation inconsistent with record type. 

42 Operation inconsistent with device type. 

43 The tcount parameter value exceeded the recsize, but the multirecord 
access aoption was not specified when the file was opened. 

44 The FUPDATE intrinsic was called, but the file was positioned at 
record zero. (FUPDATE must reference the last record read, but no 
previous record was read.) 

45 Privileged file violation. 
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Code 
(Decimal) Meaning 

46 File space on all discs in the device class specified is insufficient to 
satisfy this request. 

47 Input/output error on a file label. 

48 Invalid operation due to multiple file access. 

49 Unimplemented function. 

50 The account referenced does not exist. 

51 The group referenced does not exist. 

52 The referenced file does not exist in the system (permanent) file 
domain. 

53 The referenced file does not exist in the job temporary file domain. 

54 The file reference is invalid. 

55 The referenced device is not available. 

56 The device specification is invalid or undefined. 

57 Virtual memory is not sufficient for the file specified. 

58 The file was not passed (typically, a request for $OLDPASS when there 
is no $OLDPASS). 

-* 59 Standard label violation. 

60 Global RIN not available. 

61 Group disc file space exceeded. 

62 Account disc file space exceeded. 

63 Non-sharable device (ND) capability required, but not assigned. 

64 Multiple RIN (MR) capability required, but not assigned. 

66 Plotter limit switch reached. 

67 Paper tape error. 

68 System internal error. 

69 Miscellaneous (ATTACHIO) input/output error. 

70 Header or trailer I/O error. 

71 Process file access information area exhausted. (Try preparing with 
NOCB.) 

72 Invalid file number. 

73 Bounds check violation. 

76 Input buffer absent in IOWAIT. 

77 NO -WAIT input /output operation is pending. 

78 There is no NO -WAIT input/output for any file. 

79 There is no NO -WAIT input/output for file specified. 

80 Configured maximum number of spoolfile sectors would be exceeded 
by this output request. 

81 No SPOOL class defined in system. 

82 Insufficient space in SPOOL class to honor this input/output request. 

83 Extent size exceeds maximum allowable. 

84 The next extent in this spoolfile resides on a device which is unavail- 
able to the system (i.e., the device is :DOWN). 

85 Operation inconsistent with spooling, e.g., attempt to read hardware 
status. 

86 Spool process internal error. 

87 Offset to data is greater than 255 sectors. 

88 Spooling error. 

89 Power failure. 
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Code 
(Decimal) Meaning 

90 The calling process requested exclusive access to a file to which another 
process has access. 

91 The calling process requested access to a file to which another process 
has exclusive access. 

92 Lockword violation. 

93 Security violation. 

94 Creator conflict in use of FRENAME intrinsic (user is not the creator). 

95 "BROKEN" terminal read. 

96 Miscellaneous disc input/output error (device may require HP Customer 
Engineer attention). 

97 CONTROL Y processing requested, but no CONTROL Y pin exists. 

98 Input/output read time has overflowed. 

99 Magnetic tape error. Beginning of tape (BOT) found while requesting 
a backspace record (BSR) or a backspace file (BSF). 

100 Duplicate file name in the system file directory. 

101 Duplicate file name in the job temporary file directory. 

102 Directory input/output error. 

103 System directory overflow. 

104 Job temporary directory overflow. 

105 Illegal variable block structure. 

106 Extent size exceeds maximum allowable. 

107 Offset to data greater than 255 sectors. 

108 Inaccessible file due to a bad file label. 

109 Illegal carriage - control option . 

110 The intrinsic attempted to save a system file in the job temporary file 
directory. 

111 User lacks save files (SF) capability. 

112 User lacks private volumes (UV) capability. 

113 Volume set not mounted — mount problem. 

114 Volume set not dismounted — dismount problem. 

115 Attempted rename across volume sets. 

116 Invalid tape label FOPEN parameters. 

117 Attempted to write on an unexpired tape file. 

118 Invalid header or trailer tape label. 

119 Input/ output error positioning tape for tape labels. 

121 Tape label lockword violation. 

122 Tape label table overflow. 

123 End of tape volume set. 

124 Append request to labelled tape. 

126 Character set number must be between and 31. 

127 Form number must be between and 31. 

128 Logical page number must be between and 31. 

129 Vertical format number must be between and 31. 

130 Number of copies must be between 1 and 32767. 

131 Number of overlays must be between 1 and 8. 

132 Page length parm must be between 12 (=3") and 68 (=17") . 
139 Deleted sectors on IBM diskette. 

148 Inactive RIO record accessed. 
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Code 
(Decimal) Meaning 

149 Missing item number or return variable. 

150 Invalid item number. 

151 Undefined file type (invalid file type in FOPTION of FOPEN). 

152 Unrecognized key word in FOPEN device parameter. 

153 Expecting ";" or "cr" in FOPEN device parameter. 

154 Environment file open error. 

155 File not environment file. Check file code or record size. 

156 Header record incorrect. 

157 Uncompiled environment file. 

158 Error reading environment file. 

159 Error closing environment file. 

160 Error doing FDEVICECONTROL from environment file. 

161 Too many parameters in device string— overflow. 

162 Expecting "=" after keyword in device parameter.. 

163 "ENV" back reference in file equation incorrect. 

164 Device parameter too large or missing carriage return. 

165 Invalid density specification. 

166 FFILEINFO failed in accessing remote spoolfile. 

167 Spoolfile label error, can't insert ENV file name. 

170 The record is marked deleted. FPOINT positioned pointer to a record 
that was marked for deletion. 

171 Duplicate key value (KSAM error). 

172 No such key (KSAM error). 

173 Tcount parameter larger than record size (KSAM error). 

174 Cannot get extra data segment (KSAM error). 

175 Internal KSAM error. 

176 Illegal extra data segment (KSAM error). 

177 Too many extra data segments for this process (KSAM error). 

178 Not enough virtual memory for extra data segment (KSAM error). 

179 File must be locked before issuing this intrinsic (KSAM error). 

180 The KSAM file must be rebuilt because this version of KSAM does not 
handle the file built by previous version. 

181 Invalid key starting position (KSAM error). 

182 File is empty (KSAM error). 

183 Record does not contain all keys (KSAM error). 

184 Invalid record number (KSAM FFINDN intrinsic error). 

185 Sequence error in primary key (KSAM error). 

186 Invalid key length (KSAM error). 

187 Invalid key specification (KSAM error). 

188 Invalid device specification (KSAM error). 

189 Invalid record format (KSAM error). 

190 Invalid key blocking factor value (KSAM error). 

191 Record does not contain search key for deletion. Specified key value 
points to record which does not contain that value. 

192 System failure occurred while KSAM file was opened. 

201 Invalid ID sequence (CS error). 

202 Invalid telephone number (CS error). 

203 No telephone list specified (CS error). 
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Code 
(Decimal) Meaning 

204 Unable to allocate an extra data segment for DS/3000. 

205 Unable to expand the DS/3000 extra data segment. 

212 File number returned from 10 WAIT is not a DS line number. 

214 The requested DS line has not been opened with a user :DSLINE 

command. 

216 Message rejected by remote computer (DS error). 

217 Insufficient amount of user stack available (DS error). 
221 Invalid DS message format. (Internal DS error.) 

240 Local communication line not opened by operator (DS error). 

241 DS line in use exclusively or by another subsystem. 

242 Internal DS software malfunction. 

243 Remote computer not responding (DS error). 

244 Communications interface error. Remote computer reset the line. 

245 Communications interface error. Receive timeout. 

246 Communications interface error. Remote computer has disconnected. 

247 Communications interface error. Local timeout. 

248 Communications interface error. Connect timeout. 

249 Communications interface error. Remote computer rejected connection. 

250 Communications interface error. Carrier lost. 

251 Communications interface error. The local data set for the DS line went 
not ready. 

252 Communications interface error. Hardware failure. 

253 Communications interface error. Negative response to the dial request 
by the operator. 

254 Communications interface error. Invalid input/output configuration. 

255 Communications interface error. Unanticipated error condition. 

CONDITION CODES 

CCE Request granted. 

OV^VjT !>IUUl'CtUHlCU Uy WHO IXIULJUIOX^. 

CCL Request denied because filenum was invalid or a bounds violation 

occurred while processing this request and errorcode is 73. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Page 10-68 
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INTRINSIC NUMBER 9 Closes a file. 



■ IV IV IV 

$Cl£>SE(filertum,disp0siti0tt,seecode} t 

The FCLOSE intrinsic terminates access to a file. This intrinsic applies to files on all devices. 
FCLOSE deletes the buffers and control blocks through which the user process accessed the file. It 
also deallocates the device on which the file resides and it may change the disposition of the file. If 
you do not issue FCLOSE calls for all files opened by your process, such calls are issued automati- 
cally by MPE when the process terminates. All magnetic tape files are left offline after an FCLOSE 
to indicate to the console operator that they may be removed. 

The FCLOSE intrinsic can be used to maintain position when creating or reading a labeled tape file 
that is part of a volume set. If you close the file with a disposition code of 3, the tape does not 
rewind, but remains positioned at the next file. If you close the file with a disposition code of 2, the 
tape rewinds to the beginning of the file but is not unloaded. A subsequent request to open the file 
does not reposition the tape if the sequence (seq) subparameter is NEXT, or default (1). A 
disposition code of 1 (rewind and unload) implies the close of an entire volume set. 

When the logical end-of-data is encountered during reading, the CCG condition code is returned to 
the user process. On magnetic tape, the end-of-data can be denoted by a physical indicator such as a 
tape mark. When a file is read that spans more than one volume of labeled magnetic tape, the user 
program is suspended until the operator has completed mounting the next tape. CCG is not returned 
when end-of-tape is encountered. On disc, the end-of-data occurs when the last logical record of the 
file is passed. In this case, the CCG condition code is returned and no record is read. If the file is 
embedded in an input source containing MPE commands, the end-of-data is indicated when an 
:EOD command is encountered, but the :EOD command itself is not returned to the user. The 
end-of-data is indicated by a hardware end-of-file , including :EOF:, or on $STDIN by any record 
beginning with a colon, or on $STDINX by :EOD. In addition, on the standard input device for a 
job, as opposed to a session, :JOB, :EOJ, or :DATA indicate end-of-data. 

PARAMETERS 

fllenum integer by value (required) 

A word identifier supplying the file number of the file to be closed. 

disposition integer by value (required) 

Indicates the disposition of the file, significant only for files on disc and 
magnetic tape (ignored by Foreign Disc Facility). This disposition can 
be overridden by a corresponding parameter in a :FILE command 
entered prior to program execution. The disposition options are defined 
by two-bit fields, as follows: 

(13:3) Domain Disposition 

NOTE 

Bit groups are denoted using the standard SPL notation. 
Thus, bits (13:3) indicates bits 13, 14, and 15. 
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- No change. The disposition code remains as it was before the file 
was opened. Thus, if the file is new, it is deleted by FCLOSE; other- 
wise, the file is assigned to the domain to which it belonged previously. 
An unlabeled tape file is rewound. If the file resides on a labeled tape, 
the tape is rewound and unloaded. 

1 - Permanent file. If a disc file, it is saved ia the system file domain. If 
the file is a new or old temporary file on disc, an entry is created for it 
in the system file directory. An error code is returned, and the file 
remains open, if a file of the same name already exists in the directory. 
If the file is an old permanent file on disc, this disposition value has no 
effect. If the file is stored on magnetic tape, that tape is rewound and 
unloaded. 

2 - Temporary job file (rewound). The file is retained in the user's 
temporary (job/session) file domain and can thus be requested by any 
process within the job/session. If the file is a disc file, the uniqueness 
of the file name is checked. If a file of the same name in the temporary 
file domain exists already, an error code is returned and the file remains 
open. If the file resides on unlabeled magnetic tape, the tape is re- 
wound. If the file resides on labeled magnetic tape, the tape is back- 
spaced to the beginning of the presently opened file. 

3 = Temporary job file (not rewound). This option has the same effect 
as disposition code 2, except that tape files are not rewound. In the 
case of unlabeled magnetic tape, if this FCLOSE is the last done on the 
device (no other OPENs outstanding) the tape is rewound. If the 
file resides on a labeled magnetic tape, the tape is positioned to the 
beginning of the next file on the tape. Note that this disposition does 
not apply to disc files. 

4 = Released file. The file is deleted from the system. 

NOTE 



t in. _i_ j_i_ _ 



Aiwiougn me Dasic mncuons covering magnetic tape iues are 
covered above in dispositions through 4, it is recom- 
mended that you read the discussion of magnetic tape files 
in Section X for special considerations not here. I 



(12:1) Disc Space Disposition (for fixed length and undefined format 
files only). 

1 = Returns to the system any disc space allocated beyond the end- 
of-file indicator. The EOF becomes the file limit. No records may be 
added to the file beyond this new limit. 

Note: No space will be returned to the system if used with variable 
length files. 

= Does not return any disc space allocated beyond the end-of-file 
indicator. 
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seccode 



When a file is opened by the FOPEN intrinsic, a file count (maintained 
by the system) is incremented by one. When the file is FCLOSEd, the 
file count is decremented by one. If more than one FOPEN is in effect 
for a particular file, its disposition is saved but not affected by the 
FCLOSE call until the file count is decremented to zero. Then the 
effective (saved) disposition is the smallest non-zero disposition 
parameter specified among all FCLOSE calls issued against the file. For 
example, a file XYZ is opened three successive times by a process. The 
first FCLOSE disposition is 1, the second FCLOSE disposition is %14, 
and the third (and last) FCLOSE disposition is %12. The final 
disposition on the file XYZ will be disposition 1 (permanent file and no 
return of disc space). 

Bits (0:12) are reserved for MPE and should be set to zero. 

integer by value (required) 

Denotes the type of security initially applied to the file, significant only 

for new permanent files (ignored by Foreign Disc Facility). The options 

are: 

— Unrestricted access — the file can be accessed by any user, unless 
prohibited by current MPE provisions. 

1 — Private file creator security — the file can be accessed only by its 
creator. 



CONDITION CODES 

CCE The file was closed successfully. 

CCG 



CCL 



Not returned by this intrinsic. 

The file was not closed, perhaps because an incorrect filenum was 
specified, or because another file with the same name and disposition 
exists in the system. Additionally, an illegal disposition, 5, 6, or 7, was 
specified. This can be detected by FCHECK returning an error 49. 



SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Page 10-39 
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Performs control operations on a file or device. INTRINSIC NUMBER 13 

, IV IV L 

FCONTROUfilenum,controIcode,param); 

The FCONTROL intrinsic performs various control operations on a file or on the device on which 
the file resides. 

These operations include: 

• Supplying a printer or terminal carriage-control directive. 

• Verifying input/output. 

• Reading the hardware status word pertaining to the device on which the file resides. 

• Setting a terminal's time-out interval. 
» Rewinding a file. 

• Writing an end-of-file indicator. 

• Skipping forward or backward to a tape mark. 

The FCONTROL intrinsic applies to files on disc, tape, terminal, or line printer. Note the special 
conditions that exist when FCONTROL is used with files on labeled magnetic tape. Some FCON- 
TROL functions cannot be used with labeled tapes, and other functions may produce unexpected 
results. (Refer to controlcodes 5, 6, 7, 8, and 9.) 

PARAMETERS 

filenum integer by value (required) 

A word identifier supplying the file number of the file for which the 
control operation is to be performed. 

controlcode integer by value (required) 

An integer specifying the operation to be performed: 

- General Device Control. The param parameter is transmitted to the 
appropriate device driver, and the value returned is transmitted to the 
user through the param parameter. 

1 - Line Control. A request to send the value specified in the param 
parameter to the terminal or line printer driver as a carriage-control 
directive. Use line controls provided by FWRITE when directing to a 
disc or a spooled file. 

2 - Complete Input/Output. This insures that requested input/output 
has been physically completed. Valid only for buffered files. Posts the 
block being written whether full or not. 
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3 - Read Hardware Status Word. This operation will return in param 
the status word from the device on which the file resides. The returned 
value is the status of the device from the previous input/output opera- 
tion, including FOPEN of the file. 

4 - Set Time-Out Interval. This code indicates that a time-out interval is 
to be applied to input from the terminal. If input is requested from the 
terminal but is not received in this interval, the FREAD request termi- 
nates prematurely with condition code CCL. The interval itself is speci- 
fied, in seconds, in a word on the user's stack, indicated by param. If 
this interval is zero, any previously established interval is cancelled, and 
no time out occurs. Controlcode 4 is ignored if the addressed file is not 
being read from the terminal. Note that this only affects the next read. 

5 - Rewind File. This repositions the file at its beginning, so that the 
next record read or written is the first record in the file. This code is 
not valid for files accessed with append -only. Note that on a labeled 
magnetic tape file, the tape is positioned to the beginning of the opened 
file, and not necessarily to the beginning of the volume. 

6 - Write End-of-File. This operation is used to denote the end of a file 
on disc or magnetic tape, and is effective only for those devices. If 
applied to a disc file, the operation writes a logical end-of-data indicator 
at the point where the file was last accessed. The disc file label also is 
updated and written to disc. If the file is an unlabeled magnetic tape 
file, a tape mark is written at the current position of the tape. This 
controlcode is not allowed for labeled magnetic tape files. 

7 - Space Forward to Tape Mark. This moves a magnetic tape forward 
until a tape mark is enountered. If used on labeled magnetic tapes, the 
tape is positioned to the beginning of user trailer labels, if any. 

8 - Space Backward to Tape Mark. On unlabeled tapes, this moves a 
magnetic tape backward until a tape mark is encountered. If used on 
labeled tapes, the tape is positioned to the beginning of user header 
labels, if any. 

9 - Rewind and Unload Tape. This repositions a magnetic tape file at 
its beginning and places the tape offline. Not allowed for labeled tapes. 

NOTE 

Control codes and 3 will be rejected for spooled devicefiles. 
Control codes 5 through 9 (magnetic tape control) will be 
rejected for spooled :DATA tapes. Control codes 6 and 9 will 
be rejected for labeled magnetic tape files. 

Although the basic functions covering magnetic tape files are 
covered above, it is recommended that you read the discus- 
sion of magnetic tape files in Section III for special considera- 
tions not covered here. 

2-58 DEC 1981 



FCONTROL 



The following values for controlcode are used for changing terminal characteristics. See Section V. 

10 = Change terminal input speed. 

11 = Change terminal output speed. 

12 = Turn echo facility on. 

13 = Turn echo facility off. 

14 = Disable the system break function. 

15 = Enable the system break function. 

16 = Disable the subsystem break function. 

17 = Enable the subsystem break function. 

18 = Disable tape mode option. 

19 = Enable tape mode option. 

20 = Disable the terminal input timer. 

21 = Enable the terminal input timer. 

22 = Read the terminal input timer. 

23 = Disable parity checking.* 

24 Enable parity checking.* 

25 = Define line -termination characters for terminal input. 

26 = Disable binary transfers. 

27 = Enable binary transfers. 

28 = Disable user block mode transfers. 

29 = Enable user block mode transfers. 

34 = Disable line deletion echo suppression. 

35 = Enable line deletion echo suppression. 

36 = Set parity.* 

37 = Allocate a terminal. 

38 = Set terminal type. 

39 = Obtain terminal type information. 

40 = Obtain terminal output speed. 

41 = Set unedited terminal mode. 

a r. _ ai i i:__ -\rr\ ni»TniTJAi./imi/«4 

to — /\uurus peiiunig nu-vinii J-/'-' ic^nGou. 

45 = Enable/Disable extended wait. 

46 = Enable/Disable reading writer's ID. 

47 = Nondestructive read. 



*In Series 30/33 environment, FCONTROL code 36 only sets parity sense. You must additionally I 
use control code 23/24 to disable/enable parity checking. ■ 
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param logical (required) 

If controlcode is 1, param denotes a word containing the value to be 
transmitted to the terminal or line printer driver as a carriage control or 
mode control directive. The carriage control directive is selected from 
figure 2-3, following FWRITE. 

The mode control determines whether any carriage control directive 
transmitted through the FWRITE intrinsic takes effect before printing 
(pre-space movement) or after printing (post-space movement). The 
mode control directive is selected from the octal codes %400 or %401 
in figure 2-3. 

If param contains a mode control directive, then a value is returned to 
param that shows the mode setting of the device as it was before the 
call to FCONTROL, as follows: 

Value Meaning 

Post-spacing 

1 Pre-spacing 

If controlcode is 4, param denotes a word in the user's stack that 
contains the time-out interval, in seconds, to be applied to input from 
the terminal. 

If controlcode is 2, 5, 6, 7, 8, or 9, param is any variable or word 
identifier. This parameter is needed by FCONTROL to satisfy the 
internal requirements of the intrinsic. It serves no other purpose, 
however, and is not modified by the intrinsic. 

See Section V tor param requirements when controlcode is 10 or greater. 

CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because an error occurred. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Pages 5-1 and 10-79 
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INTRINSIC NUMBER 53 



idds a variety of control directives to a spooled device file, 
currently only device files of the 2680 page printer. 



IV LA IV TV 

FDEVICECONTROL (ftienum, target, icount, controlcode. 

>£SSS2S. SI S iK3fi IliilSilS til 31 



FDEVICECONTROL may be used to download character sets, forms and internal or control tables 
used in printing. It may also be used to control the page size, pen positioning, use of character sets 
and forms, and the number of copies of each page to be printed, along with other characteristics of 
the printing environment. The IFS/3000 intrinsics (which perform the same functions as FDEVICE- 
CONTROL), together with the layout of character set and form set load records and the Logical 
Page Table, are discussed in the IFS/3000 manual, part number 36580-90001. 

PARAMETERS 



filenum 



integer by value (required) 

A word identifier supplying the file number of the spoolfile. This value 

is obtained from FOPEN. 



target 



logical array (required) 

This array contains data to be passed to the 2680 printer. In general, 

it contains character sets, forms, or VFC information. 



tcount 



controlcode 



integer by value (required) 

The length of target in words or, if the value is negative, in bytes. 

integer by value (required) 

The code number of the operation to be performed. 



paraml, param2 



logical by value (required) 

For each value of controlcode, there may be several possible values for 

nnrnm 1 and naram2- which define the operation in more detail. 



errnum 



integer (required) 

The File System error code returned if an error occurs. Otherwise set 



to zero. 
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The following is a summary of the controlcodes described below: 
Controlcode Meaning 

128 Character Set Selection 

129 Logical Page Activation/Deactivation Request 

130 Relative Pen Displacement 

131 Absolute Pen Move 

132 Define Job Characteristics 

133 Define the Physical Page 

134 Download/Delete Character Set 

135 Download/Delete Form 

136 Download Logical Page Table 

137 Download Multi-copy Form Overlay Table 

138 Download/Delete Vertical Format Control 

140 Page Control 

141 Clear Environment 

142 Reserved 

143 Load the Default Environment 

Controlcode = 128 Character Set Selection 

paraml (8:8) primary character set identification 

param2 (8:8) secondary character set identification 

The 2680 can contain up to 32 character sets, thus allowing the use of a 
variety of fonts, styles, print rotations, and languages. Use controlcode 
134 to download character sets to the printer. Use this controlcode to 
select any two downloaded character sets to be the current primary and 
secondary character sets. 

To change the secondary character set a character at a time, set the 
eighth bit of the byte coding for the desired ASCII character. The 2680 
will strip out this bit and print, in the secondary character set, the 
character represented by the remaining 7 bit value. To change to the 
secondary character set for a number of characters and over several 
lines, insert a shift -out control character (control N) in the data. Insert 
a shift -in control character (control O) where you again wish to use the 
primary character set. 
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Controlcode = 129 



paraml (0:1) 



(1:1) 



param2 (0:8) 



Logical Page Activation/Deactivation Request 

deactivates the Logical Page Table entry identified in 
the left byte of param2. 

activates the Logical Page Table entry identified in 
the right byte of param2. 

Logical Page Table entry (from to 31) to be de- 
activated. 



(0:8) Logical Page Table entry (from to 31) to be acti- 
vated. 

Every physical page is composed of one or more logical pages. When the 
2680 begins to print each physical page, it scans the Logical Page Table 
for the first logical page labeled as active. The printer then continues 
searching the table sequentially for active pages and printing them 
until it has printed the last active page. At this point the 2680 performs 
a physical page eject and starts the sequence again. There must be at 
least one active LPT entry while the 2680 is printing. 

This controlcode allows you to cancel or enable the printing of logical 
pages during a job through the activation or deactivation of those pages. 



Controlcode = 130 



paraml 



param.2 



Relative Pen Displacement 

is a 16 bit signed integer containing the desired X displace- 
ment of the pen from its current position. 

is a 16 bit signed integer containing the desired Y displace- 
ment of the pen from its current position. 



No pen movement will result from requests to move the pen off of the 
logical page. As the coordinate system is based upon the current logical 
page itself and not upon the page's orientation with respect to the 
printer, you need not consider how the page has been rotated when 
assigning displacement values to paraml and param2. 
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Controlcode = 131 Absolute Pen Move 

paraml is an integer containing the X coordinate of the point to 
which you wish to move the pen. 

param2 is an integer containing the Y coordinate of the point to 
which you wish to move the pen. 

The values in paraml and param2 are measured from the upper left 
corner of the logical page. As with controlcode 130, you need not take 
page rotation into account when assigning coordinates, and the printer 
will not move the pen if the location you specify is off the logical page. 

Controlcode = 132 Define Job Characteristics 

paraml (0:1) 1 — the printer will print no job separation marks until 
the next job is open. 

(1:1) 1 — param2 contains the maximum allowable number 
of copies of each page. 

param2 is significant only if paraml (1 :1) is set, and is the maximum 
number of copies the printer will make of any one page for 
the current job. The default maximum is 32,767. 

The Spooler calls FDEVICECONTROL with this value of controlcode 
to set the maximum allowable number of copies per page. You may 
request any number less than or equal to this number by using control- 
code 133. 
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Controlcode = 133 Define the Physical Page 

Paraml (0:1) 1— turn ON Multi Copy Form Overlay feature. 

(1:1) 1— turn OFF Multi Copy Form Overlay feature. 

(2:1) 1— reserved 

(3:1) 1— redefine the physical page length. 

(4:1) 1— redefine the number of copies of each page de- 
sired. 

(5:1) 1— reserved 

(6:1) 1— reserved 

(7:1) 1— reserved 

(8:8) New physical page length in units of .25 inches. The 
length may not be less than 3.0 inches (a value of 
12) or greater than 17.0 inches (a value of 68). 

param2 contains the number of copies of each page you want to print. 
If this number exceeds the maximum defined in param2 of 
controlcode 132, only the maximum number of copies is 
printed. 

Although FDEVICECONTROL will accept page length values that are 
multiples of .25 inches, the 2680 printer is able to produce only pages 
that are multiples of .5 inches. For this reason, only use even number 
values in paraml (8:8). In other words, bit 15 must always be zero. 
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Paraml (0:1 



FDEVICECONTROL 

Download/Delete Character Set 

0— Download of character set into the 2680. 

1— Purge the character set identified in the right 
hand byte of param2 from the 2680. 

Param2 (0:1) 0— This is the first record of a load. 

1— This record is a continuation of the previous 
record. 



(8:8) 



Character set identifier (0-31) 



If you attempt to download a character set having the same identifier 
as one already present in the printer, then the 2680 will purge the 
already present character set and repack the user area before loading 
the new font. However, before the modification of the user area, the 
2680 prints all data currently in its buffer, as it does whenever you 
load, overlay, or delete a character set, form, or Vertical Format Con- 
trol set. 



Controlcode = 135 



Paraml (0:1) 



Download/Delete Form 

0— Load the form set identified in the right hand 
byte of param2. 

1— Purge the identified form set from the 2680 
printer's memory. 



Param2 (0:1) 0— This is the first record of a load. 

1 — This record is logically a continuation of the pre- 
vious record. 



(8:8) 



Form set identifier (0:31). 



FDEVICECONTROL will treat form sets with the same identifying 
integer in a way analogous to its treatment of character sets with the 
same identifiers. See controlcode 134. 
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Controlcode = 136 Download Logical Page Table 

Paraml is not used. 

Param2 (0:1) — This is the first record of a load. 

1— This record is logically a continuation of the 
previous record. 

A logical page is a page of data that may or may not take up an entire 
sheet of paper. It is possible to print up to 8 logical pages on one 
physical page. The Logical Page Table, 513 words long, contains some 
of the information needed to print up to 32 logical pages, so that the 
set of up to 8 logical pages printed on any one physical page may be 
varied. 

Controlcode = 137 Download Multi-copy Form Overlay Table 

Paraml is not used. 

Param2 is not used. 

This operation allows you to emulate a multi-part carbon by print- 
ing up to 8 copies of a page, each on one or two different forms. 
FDEVICECONTROL downloads into the printer's memory a table 
containing one word of information for each of the 8 possible copies 
to be overlay ed with a form. The format of each word of the table is: 

Bit (0:1) — Forml is to be overlayed on the physical page. 

(1:1) — Form2 is to be overlayed on the physical page. 

(2:4) —Reserved 

(6:5) — Forml identifier — an integer from to 31. 

(11:5) — Form2 identifier — an integer from to 31. 
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Controlcode = 138 



Download/Delete Vertical Format Control 



Paraml (0:1) 



0- 

1- 



Load a VFC 
Delete a VFC 



Param2 (0:1) 0— This is the first record of a load. 

1 — This record is logically a continuation of the 
previous record. 

(8:8) VFC set identifier (0-31). 

The Vertical Format Control table is an ASCII file downloaded to the 
2680 printer in order to give specific instructions as to the print density, 
location of top and bottom of page, and other specifications of the 
printed page. This table is further described and illustrated in chapter 4 
of the Console Operator's Guide (part- number 32002-90004). 

The 2680 expresses the height of a printed line in dots, and the system 
uses this value to compute line positions on the page. Because these 
space measurements are relative to the top of the logical page, as 
opposed to the physical page, you may use the same or different Veri- 
cal Format Control tables for logical pages of different rotations. 



Controlcode = 140 



Page Control 



Paraml (15:1) 1- 



Do a physical page eject before going to the 
specified logical page. This bit has no effect if 
this is the first record since an environment load, 
FOPEN or FCLOSE. 



(13:2) Auto eject mode. 

0— Use auto eject flag of last data record (default at 
start of job is auto eject enabled). 

1— Enable auto eject (select VFC channel 1 on new 
page). 

2— Disable auto eject (position pen at top of page.) 

Param2 (8:8) Logical page number (0 to 31). 

The logical page identified in param2 becomes the current logical page 
even if other logical pages have entries which precede it in the Logical 
Page Table. FDEVICECONTROL activates the specified page if it is 
inactive, and the 2680 performs a physical page eject if bit (15:1) of 
paraml is set. 
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Controlcode = 141 Clear Environment 

paraml (0:1) 1 — clear all character sets 
(1:1) 1 — clear all forms 
(2:1) 1 — clear all Vertical Format Controls (VFCs) 

param2 is not used. 

The printer will flush all data currently in its buffers, and then perform 
the indicated clears, if any. 

Controlcode = 142 Reserved 



Controlcode = 143 Load the Default Environment 

paraml is not used. 

param2 is not used. 

The 2680 printer flushes all data, erases the user area, and loads the 
default character set, the Vertical Format Control (VFC), and the 
Logical Page Table (LPT). 

CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because an error occurred. 

TEXT DISCUSSION 

None. 
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Deactivates a RIO record 



IV DV O-V 

FDELE'i E {Jiiemtffirreemm) 

FDELETE deactivates a specified logical record. If no record is specified (or the recnum is 
negative) the next random access logical record becomes inactive. If the selected record has already 
been deactivated a CCE condition code is returned. The condition can be detected by calling the 
FCHECK intrinsic. The "inactive record" error indicates that the record selected for this FDELETE 
was already inactive. 



PARAMETERS 

filenum integer by value (required) 

A word identifier supplying the file number of the file to be de- 
activated. 






double by value (optional) 

A positive double integer representing the relative logical record to be 

modified. 



CONDITION CODES 

CCE Request granted. No error (although inactive record may have been 

encountered). 

qqq Request denied. End of file. 

CCL Request denied. Access error. 



IfcXl uidiruaaiura 
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INTRINSIC NUMBER 307 



Returns message corresponding to FCHECK error number. 






The FERRMSG intrinsic causes a message to be returned to msgbuf that corresponds to an 
FCHECK error number. This makes it possible to display an error message from your program. The 
message describes the error associated with the error number provided in the errorcode parameter. 

PARAMETERS 



errorcode 



msgbuf 



integer (required) 

A word identifier containing the error code for which a message is to be 

returned. It should contain an error number returned by FCHECK. 

logical array (required) 

A logical array to which the message associated with errorcode is 
returned by FERRMSG. In order to contain the message string, msgbuf 
must be a maximum of 72 characters long. 



msglgth 



integer (required) 

A word identifier to which is returned the length of the msgbuf string. 

The length is returned as a positive byte count. 



CONDITION CODES 



CCE 
CCL 

CCG 



Request granted. 

Request not granted because no error message exists for this errorcode 
or because of a message system error. 

Request not granted, msgbuf address may be out of bounds, msgbuf 
may not be large enough, or msglgth address is out of bounds. 



TEXT DISCUSSION 
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Provides access to file information. 

IV IV BA 

FPIi-EINFO ifiieaum [Jtemtwrnl , iteminlucl j 
[Jtemnum2 iittmmttte2} 
[JUmnumS. ifrirmiLui Sf 
f,itemnum4, fcemvatueti-i 
[jtemnumS, itemi>alue5}}; 

NOTE 

Itemnum/itemvalue parameters must appear in pairs. Up to five 
items of information can be retrieved by specifying one or more 
itemnum/itemvalue pairs. 

FFILEINFO provides access to file information. It is designed to be extensible so that new file 
information can be defined and accessed. 



PARAMETERS 

filenum integer by value (required) 

MPE file number returned by FOPEN 

itemnum integer by value (optional) 

Cardinal number of the item desired; this specifies which item value is 

to be returned. 

(See item #, Figure 2-la) 

itemvalue byte array (optional) 

Value of the item specified by the corresponding itemnum; the data 
type of the item value depends on the item itself. 
(See item, Figure 2-la) 



CONDITION CODES 

CCE No error 

CCG Not used 

CCL Access or calling sequence error 

TEXT DISCUSSION 

Page 10-68 
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ITEM# TYPE ITEM UN 'TS 

33 I label type (see Label Tapes) 

34 | current number of writers (see IPC) 

35 I current number of readers (see IPC) 

36 L File Allocation Date (CALENDAR format) 

37 D File Allocation (CLOCK format) 

38 L SPOOFLE Device file number (#0 or #1 (see File Code) 

number) 

39 RESERVED 

40 D disc or diskette device status 

41 I device type 

42 I device subtype 

43 BA environment file name 

44 I last disc extent allocated 

45 BA file name from labeled tape HDR1 record 

46 I tape density BPI 

47 i DRT number 

48 I UNIT number 

49 I software interrupt PLABEL 



I 
I 



Figure 2-la. Item Values Returned by FFILEINFO (Continued) 
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ITEM# 


TYPE 


ITEM 




UNITS 


1 


BA 


filename 


(seeFGETINFO) 




2 


L 


foptions 


(seeFGETINFO) 




3 


L 


aoptions 


(see FGETINFO) 




4 


I 


recsize 


(see FGETINFO) 


words/bytes 


5 


I 


devtype 


(seeFGETINFO) 




6 


L 


Idnum 


(seeFGETINFO) 




7 


L 


hdaddr 


(seeFGETINFO) 




8 


I 


filecode 


(seeFGETINFO) 




9 


D 


recpt 


(see FGETINFO) 




10 


D 


eof 


(see FGETINFO) 




11 


D 


flimit 


(see FGETINFO) 


records 


12 


D 


logcount 


(see FGETINFO) 


records 


13 


D 


physcount 


(see FGETINFO) 


records 


14 


! 


blksize 


(see FGETINFO) 


words/bytes 


15 


L 


extsize 


(see FGETINFO) 


sectors 


16 


I 


numextents 


(seeFGETINFO) 




17 


I 


userlabels 


(see FGETINFO) 




18 


BA 


creatorid 


(see FGETINFO) 




19 


D 


labaddr 


(see FGETINFO) 




20 


I 


blocking factor 


(see FOPEN) 




21 


I 


physical block size 




words 


22 


I 


data block size 




words 


23 


I 


offset to data in blocks 




words 


24 


I 


offset to Active Record Table within the block 


(RIO files) 


words 


25 


I 


size of Active Record Table 




words 


26 


BA 


vol. ID (label tape) 


(see Label Tapes) 




27 


BA 


vol. set ID (label tape} 


(see Label Tapes) 




28 


I 


expiration date (Julian format) 


(see Label Tapes) 




29 


I 


file sequence number 


(see Label Tapes) 




30 


I 


reel number 


(see Label Tapes) 




31 


I 


sequence type 


(see Label Tapes) 




32 


I 


creation date (Julian format) 


(see Label Tapes) 





Figure 2-la. Item Values Returned by FFILEINFO 
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Requests access and status information about a file. 



TVTPttTMCTr! MTTMRT'.T? 11 



IV BA r« 1- i * L 

FGETINFO(//fem*m,/1ten<im€/opft'o^aopf(ons,rec«2e,<iOTt>pe, 

I D D 30 D D 1 -L 

lil,Hvde 1 wcpt,caMlimit,tofrounl.phy8CtmntMk*Ut',rxtHist', 

I I BA ' D 0-V 

namextentn,useriabek,creatoridMbaddr): 



Once a file is opened on any device, the FGETINFO intrinsic can be used to request access and 
status information about that file. 



PARAMETERS 

fllenum 

filename 



f options 



integer by value (required) 

A word identifier supplying the file number of the file about which 

information is requested. 

byte array (optional) 

A byte array to which is returned the actual designator of the file being 

referenced, in this format: 

f.g.a 

where 

f = the local file name. 

g = the group name (supplied or implicit). 

a = the account name (supplied or implicit). 

The byte array must be 28 bytes long. When the actual designator is 

returned, unused bytes in the array are filled with blanks on the right. 

A nameless file will return an empty string. 

Default: The actual designator is not returned. 

logical (optional) 

The foptions parameter returns seven different file characteristics by 
setting corresponding bit groupings in a 16-bit word. Correspondence is 
from right to left. The file characteristics returned are as follows. The 
bit settings are summarized in figure 2-1. 

NOTE 

Bit groups are denoted using the standard SPL notation. Thus 
bits (14:2) indicates bits 14 and 15; bits (10:3) indicates bits 
10, 11, and 12. 

Bits (14:2) — Domain Foption. 

The file domain that was searched by MPE to locate the file, indicated 

by these bit settings: 

00 - The file is a new file. 
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BITS 


(0:3) 


(3:1) 


(4:1) 


(5:1) 


(6:1) 


(7:1) 


(8:2) 


(10:3) 


(13:1) 


(14:2) 


FIELD 


(RESERVED) 


RELATIVE 
I/O 


KSAM 
FILE 


DISALLOW 
:FILE 


MPE TAPE 
LABELS 


CARRIAGE 
CONTROL 


RECORD 
FORMAT 


DEFAULT 
DESIGNATOR 


ASCII/ 
BINARY 


DOMAIN 


MEANING 




= Non- 
mo file 


= Not a new 
KSAM file 
(default) 


1 =No :FILE 


1 = LABELED 
TAPE 


= NOCCTL 


00 = Fixed 


000 = filename 


= Binary 


00 = New file 






1 = RIO file 


1 = New KSAM 
file or 
existing 
KSAM file 
opened as 
an MPE 
file 


0=:FILE 


0= NON- 
LABELED 
TAPE 


1 = CCTL 


01 = Variable 
10= Undefined 


001 =$STDLIST 

010 = $NEWPASS 

011 = $OLDPASS 

100 = $STDIN 

101 =$STDINX 
110 = $NULL 


1 = ASCII 


01 = Old System 
File 

10 = Temporary 

File 

11 = Old User 

File 



■n 
O 
m 

H 



Figure 2-1. Foptions Bit Summary 



NOTE: Double lines indicate octal digit boundaries. 
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10 = The file is an old temporary file. 

11 = The file is an old file. 

Bit (13:1) — ASCII/Binary Foption. 

For ASCII this bit is 1. For binary, it is 0. 

Bits (10:3) — Default File Designator Foption. 
The bit settings are: 

000 = The actual file designator is the same as the formal file 

designator. 

001 = The actual file designator is $STDLIST. 

010 = The actual file designator is $NEWPASS. 

011 = The actual file designator is $OLDPASS. 

100 = The actual file designator is $STDIN. 

101 = The actual file designator is $STDINX. 
110 = The actual file designator is $NULL. 

Bits (8:2) — Record Format Foption. 

The format in which the records in the file are recorded, indicated by 

these bit settings: 

00 = Fixed-length records. 

01 = Variable-length records. 
10 = Undefined-length records. 

Bit (7:1) — Carriage Control Foption. 

= No carriage-control character expected. 

1 = Carriage-control character expected. 

Bit (6:1) — MPE Tape Label Foption. 

= Non-labeled tape. 

1 = Labeled tape. 

Bit (5:1) — Disallow File Equation Foption. 

This option ignores any corresponding :FILE command, so that the 

„ — ~;«„o«,v« c in +ho PDPF.N nail take effect (unless overridden by those 

in the file label). For disallowing :FILE, this bit is set to 1; for allowing 

:FILE,thebitisO. 

Bits (4:1) - KSAM file Foption 

= Not a new KSAM file (default) 

1 = New KSAM file or existing file opened as an MPE file. 

Bits (3:1) - Relative I/O Foption 

= Non-RIO file will be created, (default) 

1 = RIO file will be created. 
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Default: Foptions are not returned. 

aoptions logical (optional) 

The aoptions parameter returns up to seven different access options 
represented by bit groupings in a 16-bit word, as described below. The 
bit settings are summarized in figure 2-2. 

Bits (12:4) — Access Type Aoptions. 

The type of access allowed users of this file, as follows : 

0000 = Read access only. 

0001 = Write access only. 

0010 = Write access only, but previous data in the file is not deleted. 
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BITS 



FIELD 



MEANING 



(0:3) 



(RESERVED) 



(3:1) 



KSAM 
ACCESS 



= KSAM 

access 
expect- 
ed 

1 = Non- 

KSAM 
access 
expect- 
ed 



(4:1) 



NO WAIT 
I/O 



1 = No-Wait 



0= Non 

No-Wait 



(5:1) 



(RESERVED) 



(6:1) 



MULTI 
ACCESS 



1 = Multi 
access 



0= Non-Multi 
access 



(7:1) 



INHIBIT 
BUFFERING 



1 =NOBUF 



= BUF 



(8:2) 



EXCLUSIVE 
ACCESS 



01 = Exclusive 



10 = Semi- 
exclusive 



1 1 = Share 



00 = Default 



(10:1) 



DYNAMIC 
LOCKING 



= No Dynamic 
Lock 



1 = Dynamic 
Lock 



Figure 2-2. Aoptions Bit Summary 



NOTE: Double lines indicate octal digit boundaries. 
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(11:1) 

MULTI- 
RECORD 
ACCESS 



1 = Multi- 
record 



= No multi- 
record 



(12:4) 



ACCESS 
TYPE 



000 = Read 
only 



001 = Write 
only 



010 = Write 

(save) 
only 

011 = Append 

only 

100 = Read/ 

write 

101 = Update 
110 = Execute 
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0011 = Append access only. 

0100 = Input/output access. 

0101 = Update access. 
0110 = Execute access. 

Bit (11:1) — Multirecord Aoption. 

For multirecord mode, this bit is set to 1; for non-multirecord mode, it 

isO. 

Bit (10:1) — Dynamic Locking Aoption. 
The bit settings are: 

I = Allow dynamic locking/unlocking. 

= Disallow dynamic locking/unlocking. 

Bits (8:2) — Exclusive Aoption. 

This aoption specifies whether a user has continuous exclusive access to 
this file, from the time it is opened to the time it is closed. The bit 
settings are: 

01 = Exclusive access. 

10 = Semi-exclusive access. 

II = Share access. 

Bit (7:1) - Inhibit Buffering Aoption. 

This option inhibits automatic buffering by MPE and allows input/ 

output to take place directly between the user's stack or extra data 

segment and the applicable hardware device. 

1 = Inhibit buffering. 

= Normal buffering 

Bit (6: 1) — Multi- Access Mode Aoption. 

This field provides the accessor with a means of sharing access to the 

file. 

1 = Multi access. 

= Non-multi access. 

Bit (5:1) - Reserved for MPE. 

Bit (4:1) - No-Wait I/O Aoption. 

This bit allows the accessor to initiate an I/O request and to have 

control returned before the completion of the I/O. 

1 = No-wait I/O in effect. 

= No-wait I/O not in effect. 

Bits (3:1) — KSAM Access Aoption 

= KSAM access 

1 = Non-KSAM access expected; KSAM key file or data file is treated as 
standard MPE file. For this setting to be meaningful, file must be a 
KSAM file (foptions 4:1 = 1). 

Bits (0:3) - Reserved for MPE. 
Default: Aoptions are not returned. 



2-70 



FGETINFO 



recsize 



devtype 



r\ 



V'V 



Idnum 



hdaddr 



filecode 



recpt 



integer (optional) 

A word to which is returned the logical record size associated with the 

file. If the file was created as a binary type, this value is positive and 

expresses the size in words. If the file was created as an ASCII type, this 

value is negative and expresses the size in bytes. 

default: The logical record size is not returned. 

integer (optional) 

A word to which is returned the type and subtype of device being used 
for the file, where 
bits (0:8) = device subtype, and 
bits (8:8) = device type. 

If the file is not spooled, which can be determined from hdaddr (0:8), 
and returned devtype is actual. The same is true if the file is spooled 
and was opened via logical device number. However, if an output file is 
spooled and was opened by device class name, devtype contains the 
type and subtype of the first device in its class, which may be different 
from the device actually used. (See the System Manager/System Super- 
visor Manual.) If you have opened a serial disc tape and type returned 
in bits (8:8) is 31 (%37) even though the real device type is as specified 
-ift-4able^>Dlassification of Devices. Device type %07 is returned by 



FGETINFO for foreign discs. 

default: The device type and subtype are not returned. 

logical (optional) 

A word to which is returned the logical device number associated with 

the device on which the file resides. 

If the file is a disc file, then the logical device number will be that of 

the first extent. If the file is spooled, then Idnum will be a virtual device 

number which does not correspond to the system configuration I/O 

device list. If the file is located on a remote computer, the left eight bits 

are the logical device number of the DS device and the right eight bits 

are the logical device number on the remote computer. 

default: The logical device number is not returned. 

logical (optional) 

A word to which the hardware address of the device is returned, where 
bits (0:8) = the Device Reference Table (DRT) number, and 
bits (8:8) = the unit number. (See limitation under special consider- 
ations). 

If the device is spooled, the DRT number will be zero and the unit 
number is undefined. 
Default: The hardware address is not returned. 

integer (optional) 

A word to which is returned the value recorded with the file as its file 
code (for disc files only). 
default: The file code is not returned. 

double (optional) 

A double word to which is returned a double integer representing the 

current logical record pointer setting. This is the displacement in logical 

records from record number in the file. It identifies the record that 

would next be accessed by an FREAD or FWRITE call. 

Default: The logical record pointer setting is not returned. 
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eof 



flimit 



logcount 



physcount 



blksize 



extsize 



numextent 



userlabels 



double (optional) 

A double word to which is returned a double positive integer equal to 

the number of logical records currently in the file. If the file does not 

reside on disc, this value will be zero. 

Default: The number of logical records in the file is not returned. 

double (optional) 

A double word to which is returned a double positive integer 

representing the number of the last logical record that could ever exist 

in the file, because of the physical limits of the file. If the file does not 

reside on disc, this value will be zero. 

Default: The file limit information is not returned. 

double (optional) 

A double word to which is returned a double positive integer 

representing the total number of logical records passed to and from the 

user during the current access of the file. 

Default: The logical record count is not returned. 

double (optional) 

A double word to which is returned a double positive integer 
representing the total number of physical input/output operations 
performed within this process against the file since the last FOPEN call. 
Default: The number of I/O operations is not returned. 

integer (optional) 

A word to which is returned the block size associated with the file. If 

the file was created as a binary type, this value is positive and expresses 

the size in words. If the file was created as an ASCII type, this value is 

negative and shows the size in bytes. 

Default: The block size is not returned. 

logical (optional) 

A word to which is returned the disc extent size associated with the file 

(in sectors). 

Default: The disc extent size is not returned. 

integer (optional) 

A word to which is returned the maximum number of disc extents 

allowable for the file. 

Default: The maximum allowable number of extents is not returned. 

integer (optional) 

A word to which is returned the number of user header labels defined 

for the file when it was created. If the file is not a disc file, this number 

is zero. When an old file is opened for overwrite output, the value of 

userlabels is not reset and old user labels are not destroyed. 

Default: The number of user labels is not returned. 
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creatorid 



labaddr 



byte array (optional) 

A byte array to which is returned the eight-byte name of the user who 
created the file. If the file is not a disc file, blanks are returned. 
Default: The user name is not returned. 

double (optional) 

A double word to which is returned the sector address of the label of 

the file. The high-order eight bits show the logical device number. The 

remaining 24 bits show the absolute disc address. If the file is not a 

disc, zero is returned. 

Default: The sector address is not returned. 



CONDITION CODES 



CCE 
CCG 
CCL 



Request granted. 

Not returned by this intrinsic. 

Request denied because an error occurred. 



SPECIAL CONSIDERATIONS 

HDADDR Error Code 5 as obtained by FCHECK: 

For large system configurations such as Series 64, if a DRT larger than 255 was requested by 
FGETINFO the request will be denied with a CCL condition code 5. To obtain a proper value for 
DRT and/or UNIT number, refer to the table of parameters in FFILEINFO. 



TEXT DISCUSSION 



Page 10-66 
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FINDJCW 

Searches the Job Control Word table for 
a specified Job Control Word. 

BA I. f 

FINDJCW ijcwimmejewttalue,statita); 

PARAMETERS 



jcwname 



jcwvalue 



status 



byte array (required) 

A byte array containing the name of the Job Control Word (JCW) to 

be found. May contain up to 255 alphanumeric characters, starting 

with a letter and ending with a non-alphanumeric character such as a 

blank. 

logical (required) 

A word identifier to which is returned the value of jcwname, if 

jcwname is found. If jcwname is not found, jcwvalue is unchanged. 

integer (required) 

A word identifier to which is returned a value denoting the execution 

status of the intrinsic, as follows: 

- Successful execution, jcwname found. 

1 - Error, jcwname greater than 255 characters long. 

2 - Error, jcwname does not start with a letter. 

3 - Error, jcwname not found in JCW table. 



CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 



Page 4-47 



2-74 



FLOCK 



±Jyn8.rniC3u.i.y *ocks s, .a.*^-. 



INTRINSIC NUMBER 15 



IV 



LV 



The FLOCK intrinsic provides a means of signaling that the caller wants temporary exclusive use of 
a file. 



PARAMETERS 

filenum 



lockcond 



integer by value (required) 

A word supplying the file number of the file to be locked. 

logical by value (required) 

A word specifying conditional or unconditional locking: 

TRUE — Locking will take place unconditionally. If the file cannot be 
locked immediately, the calling process suspends until the file 
can be locked. 
Bit 15 = 1 

FALSE - Locking will take place only if the file's RIN is not currently 
locked. If the RIN is locked, control returns immediately to 
the calling process, with condition code CCG. 
Bit 15 = 0. 



CONDITION CODES 

The condition codes possible when lockcond = TRUE are 

CCE Request granted. 

Ccg Not returned when lockcond = TRUE. 

CCL Request denied because this file was not opened with the dynamic 

locking aoption specified in the FOPEN intrinsic, or the request was to 
lock more than one file and the calling process does not possess the 

A/Tnl4.;.-.l.-. DIM rVjr-.aV>;li+TT 
lVlLULUl^XC xijJ.j.1 uwpuwuiiij . 

The condition codes possible if lockcond = FALSE are 

CCE Request granted. 

CCG Request denied because the file was locked by another process. 



ULL 



r>~~,,™+ ^oi-.icri Kp^-anco this filp was not. onened with the dynamic 
locking aoption specified in the FOPEN intrinsic, or the request was to 
lock more than one file and the calling process does not possess the 
Multiple RIN Capability. 
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INTRINSIC NUMBER 213 Obtains information about the opened logging file. 



D I ' 
FLUSHLOG f index, staim) 

The FLUSHLOG intrinsic is used to write the contents of the user logging memory buffer to the 
disc destination file. This helps to preserve the contents of the memory buffer in the event of a 
system failure. This intrinsic writes no special records. 

PARAMETERS 

index double (required) 

The parameter returned from OPENLOG that identifies the user's 
access to the logging system. 

status integer (required) 

An integer in which error information is returned to the caller. Zero 
indicates OK status. 



CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 

None. 
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SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

Standard Capability sufficient if only one file is to be locked dynamically. 

If more than one file is to be locked dynamically, the Multiple RIN Capability is required. 

TEXT DISCUSSION 

Page 10-55 
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PARAMETERS 

date 
string 



FMTCALENDAR 



Converts any calendar date with the same format as 
the CALENDAR, intrinsic into a format as follows: 

FRI, AUG 5, 1977 



LV f 8A 



logical by value (required) 

A logical value representing any calendar date with the same format as 

the CALENDAR intrinsic, 

byte array (required) 

A 17-character byte array in which the formatted calendar date is 

returned. 



CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 

Page 4-45 
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FMTCLOCK 



Converts the time of day with the same 
format as the CLOCK intrinsic into a format 
as follows: 

7:39 AM 



DV BA 
FMTClA>CK{time string) ; 



PARAMETERS 

time 
string 



double by value (required) 

A doubleword value representing the time of day with the same format 

as the CLOCK intrinsic. 

byte array (required) 

An 8-character byte array in which the formatted time of day is 

returned. 



CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 

Page 4-45 
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FMTDATE 



Converts calendar date and time of day 
with the same format as the CALENDAR 
and CLOCK intrinsics to a format, as follows: 

FRI, AUG 5, 1979 7:39 AM 



PARAMETERS 



date 



time 



string 



logical by value (required) 

A logical value with the same format as the CALENDAR intrinsic. 

double by value (required) 

A doubleword value with the same format as the CLOCK intrinsic. 

bvte array (required) 

A 27-character byte array in which the formatted date and time are 

returned. 



CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 

Page 4-45 
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INTRINSIC NUMBER 1 



Used to establish access to a file and optionally 
define the physical characteristics of the file 
prior to setting up access to it. 



I BA LV 

fil«num:^FOPK^formaldwignatorJoplu>w,aoptionH,rt-csui\deinci>.formmsgl 



LV IV BA BA 

>,device,f 



IV 



IV 



IV 



Illlllil 



IV DV 



IV 



The FOPEN intrinsic makes it possible to access a file. In the FOPEN intrinsic call, a particular file 
may be referenced by its formal file designator, described in Section III. When the FOPEN intrinsic 
is executed, it returns to the user's process a file number by which the system uniquely identifies 
the file. This file number, rather than the file designator, then is used by subsequent intrinsics in 
referencing the file. 

FUNCTIONAL RETURN 

This intrinsic returns an integer file number used to identify the opened file in other intrinsic calls. 

PARAMETERS 



formaldesignator 



foptions 



byte array (optional) 

Contains a string of ASCII characters interpreted as a formal file 

designator, as defined in Section III. This string must begin with a 

letter, contain alphanumeric characters, slashes, or periods, and 

terminate with any non-alphanumeric character except a slash or a 

period. If the string names a system-defined file, it can begin with a 

dollar sign ($); if it names a user-predefined file, it can begin with an 

asterisk (*). New KSAM files unlike standard files must be opened with 

a unique name. 

Default: A temporary nameless file that can be read from or written to, 

but not saved, is assigned. 

logical by value (optional) 

The foptions parameter allows you to specify different file charac- 
teristics by setting corresponding bit groupings in a 16-bit word. The 
correspondence is from right to left, beginning with bit 15. These char- 
acteristics are as follows, proceeding from the rightmost bit groups to 
the leftmost bit groups in the word. The bit settings are summarized in 
figure 2-1. 

NOTE 

Bit groups are denoted using the standard SPL notation. Thus 
bits (14:2) indicates bits 14 and 15; bits (10:3) indicates bits 
10, 11, and 12. 
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Bits (14:2) — Domain Foption. 

The file domain to be searched by MPE to locate the file, indicated by 

these bit settings: 

00 = The file is a new file, created at this point. No search is necessary. 

01 = The file is an old permanent file, and the system file domain 
should be searched. 

10 = The file is an old temporary file, and the job file domain should be 

scorched. 

11 = The file is an old file that is to be located by first searching the job 
file domain and then, if the file is not found, by searching the system 
file domain. 

Bit (13:1) — ASCII/Binary Foption. 

The code (ASCII or binary) in which a new file is to be recorded when 
it is written to a device that supports both codes. In the case of disc 
files, this also affects padding that can occur when a direct-write 
intrinsic call (FWRITEDIR) is issued to a record that lies beyond the 
current logical end-of-file indicator. In ASCII files, any dummy records 
between the previous end-of-file and the newly-written record are 
padded with blanks. In binary files, such records are padded with 
binary zeros. All files except mag tape and serial disc files are treated as 
ASCII files. Foreign disc files are binary records. 
For ASCII files, this bit is 1. 
For binary files, this bit is 0. 

Bits (10-3) — Default File Designator Foption. 

The actual file designator is equated with the formal file designator 

specified in FOPEN, if 

1 No explicit or implicit :FILE command equating the formal tile 
designator to a different actual file designator occurs in the job or 

session; or 

2 The Disallow File Equation Foption (bit 5) is specified. (Note that 
a leading * in a formal designator can effectively override the dis- 
allow file equation foption.) 

The bit settings are . 

000 = The actual file designator is the same as the formal file designator. 

001 = rne actual me uesiguawi. m V ui.^.^~-. 

010 = The actual file designator is $NEWPASS. 

011 = The actual file designator is $OLDPASS. 

100 = The actual file designator is $STDIN. 

101 = The actual file designator is $STDlNX. 
110 = The actual file designator is $NULL. 

Bits (8:2) — Record Format Foption. 

The format in which the records in the file are recorded, indicated by 

these bit settings: 

00 = Fixed-length records. The file is composed of logical records oi 

uniform lensth. Foreign discs always have fixed-length records. 

01 = Variable-length records. The file contains logical records of varying 

length. This format is restricted to records that are written in 
sequential order. The size of each record is recorded internally. 
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The actual physical record size used is determined by multiplying 
the recsize (specified or default) plus one by the block factor, and 
adding one word for the end-of-block indicator. This option is not 
allowed when NOBUF is specified. In such a case, the record 
format used is undefined-length records, discussed below. 

10 = Undefined-length records. The file contains records of varying 
length that were not written using the variable-length foption (01). 
All files not on disc or magnetic tape are treated as containing 
undefined-length records by default. The file system makes no 
assumption about the amount of data that is useful. The user 
must determine how much data is good. 

For undefined length records, only the data supplied is written 
with no information about its length. 

Note: Undefined-length records are supported by all devices; 
fixed- and variable-length records are supported by disc and 
magnetic tape devices only. To state this another way: disc and 
magnetic tape devices support all record formats, whereas all other 
devices support only undefined length records. 

Bit (7:1) — Carriage Control Foption. 

If selected, this specifies that you will supply a carriage control 
directive in the calling sequence of each FWRITE call that writes 
records onto the file. 

= No carriage control directive expected. 

1 = Carriage control directive expected. 

Carriage control is defined only for character oriented, i.e., ASCII, files. 
This option and binary are mutually exclusive and attempts to' open 
new files with both binary and this option results in an access violation. 

This option is a physical attribute of the file and its state cannot be 
modified when opening an old disc file. 

A carriage control character passed through the control parameter of 
FWRITE is recognized and acted upon only for files for which carriage 
control is specified in FOPEN. Embedded control is treated strictly as 
data on files for which no carriage control is specified, and does not 
invoke spacing for such files. You may specify spacing action on files 
for which carriage control has been specified, either by embedding the 
control in the record, indicated with a control parameter of one in the 
call to FWRITE, or by sending the control code directly via the control 
parameter of FWRITE. 

A carriage control character sent to a file on which the control cannot 
be executed directly, for example, line spacing to a disc or tape file, will 
result in having the control character embedded as the first byte of the 
record. Thus, the first byte of each record in a disc file having a carriage 
control character contains control information. Control sent to other 
types of files results in transmission of the control to the driver. 

The control codes %400 through %403 are remapped to %100 through 
%103 so that they fit into one byte and thus can be embedded. Records 
written to the line printer with one of the above controls should not 
contain information other than control information. 
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A record written with one of the above controls and no data (count = 
0, or imbedded control and count = 1) will not cause physical I/O of 
any sort. 

For the purpose of computing record size, carriage control information 
is considered by the file system to be part of the data record. As such, 
specifying the carriage control option adds one byte to the record size 
at the time the file is created. For example, a specification of 
REC=-132,1,F,ASCII;CCTL results in a recsize of 133 characters. 

You always may read up to and including the recsize as returned by 
FGETINFO. On writes of files for which carriage control is specified, 
however, the data transferred is limited to recsize -1 unless a control 
of one is passed indicating the data record is prefixed with embedded 
control. 

Bit (6:1) — Labeled Tape Foption. 
1 = Labeled tapes. 
= No labeled tapes. 

Bit '5:1) - Disallow File Equation Foption. 

This option ignores any corresponding :FILE command, so that the 
specifications in the FOPEN call take effect (unless preempted by those 
in the file label, for disc files). Note that a leading * in a formal desig- 
nator can effectively override the disallow file equation foption. 

= Allow :FILE. 

1 = Disallow :FILE. 

Bits (2:3) File Type Foption 

Determines the type of file to create for a new file. If the file is old, this 

field is ignored. 

000 - Ordinary file 

001 - KSAM file 

010 - Relative I/O file 

100 - Circular file (discussed in Section III) 

110 - Message file 

Note: The Default Designator FOPTION, bits 10 through 12, offers 

several choices for default file designators. Any value used other than 

for "filename" will override the File Type field. 

Specification of both the KSAM and RIO options result in an access 
violation communicated by a CCL being returned. Specifying RIO in a 
:FILE command will override the KSAM option in the FOPEN call. 

Bits (0:2) - Reserved for MPE. Should be set to zero. 

The aoptions parameter permits you to specify up to seven different 
access options established by bit groupings in a 16-bit word. These 
access options are described below. The bit settings are summarized in 
figure 2-2. 2 _ g3 
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Bits (12:4) — Access Type Aoptions. 

The type of access allowed for this access of this file: 

0000 = Read access only. The FWRITE, FUPDATE, and FWRITEDIR 

intrinsic calls cannot reference this file. The end-of-file is not 
changed; the record pointer starts at 0. 

0001 = Write access only. Any data written in the file prior to the cur- 

rent FOPEN request is deleted. The FREAD, FREADSEEK, 
FUPDATE, and FREADDIR intrinsic calls cannot reference 
this file. The end-of-file is set to 0; the record pointer starts at 
0. On magnetic tape an EOF mark will be written to the tape 
when the file is FCLOSED even if no data is written. 

0010 = Write access only, but previous data in the file is not deleted. 

The FREAD, FREADSEEK, FUPDATE, and FREADDIR 
intrinsic calls cannot reference this file. The end-of-file pointer 
is not changed, the record pointer starts at 0. Therefore, data 
will be overwritten if a WRITE is done. 

0011 = Append access only. The FREAD, FREADDIR, FREADSEEK, 

FUPDATE, FSPACE, FPOINT, and FWRITEDIR intrinsic calls 
cannot reference this file. This option is not valid for files con- 
taining variable-length records. The end-of-file pointer is used to 
set the record pointer prior to each FWRITE. For disc files it 
is updated (in an internal file system table) after each FWRITE. 
Thus, data in the file cannot be overwritten. 

0100 = Input/output access. Any file intrinsic except FUPDATE can be 

issued for this file. The end-of-file pointer is not changed, the 
record pointer starts at 0. 

0101 = Update access. All file intrinsics, including FUPDATE, can be 

issued for file. The end-of-file pointer is not changed; the record 
pointer starts at 0. 
0110 = Execute access. Allows user with Privileged Mode Capability 
input/output access to any loaded file. The end-of-file pointer is 
not changed, the record pointer starts at 0. 

Bit (11:1) — Multirecord Aoption. 

Signifies that individual read or write requests are not confined to 
record boundaries. Thus, if the number of words or bytes to be 
transferred (specified in the tcount parameter of the read or write 
request) exceeds the size of the physical record (i.e., block) referenced, 
the remaining words or bytes are taken from subsequent successive 
records until the number specified by tcount have been transferred. 
This option is available only if the inhibit buffering aopt ion, described 
below, is selected also. 

= Non-multirecord mode. 

1 = Multirecord mode. 

Bit (10:1) — Dynamic Locking Aoption (disc file only). 
Indicates that you want to use the FLOCK and FUNLOCK intrinsics to 
dynamically permit or restrict concurrent access to the file by other 
processes at certain times. The user process can continue this temporary 
locking/unlocking until it closes the file. Dynamic locking/unlocking is 
made possible through a Resource Identification Number (RIN) 
assigned to the file and temporarily acquired by the FOPEN intrinsic. 
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The calline process and other processes must use the RIN in 
cooperation to guarantee the integrity of the file, as discussed in 
Section III. Non-cooperating processes are allowed concurrent access 
at all times, unless other provisions prohibit this. You must have 
LOCK access at account, group and file levels for FOPEN to grant the 
dynamic locking aoption. (LOCK Access is available if LOCK, 
APPEND, or WRITE access is set for you at these levels.) 

= Disallow dynamic locking/unlocking. 

1 = Allow dynamic locking/unlocking. A disc file may be multiple 
accessed only if all FOPEN requests for the file specify dynamic locking, 
or if none of them do. An FOPEN request that disagrees with the cur- 
rent access, if any, will fail. This bit is ignored for non-disc files. 

Bits (8:2) — Exclusive Aoption. 

This aoption specifies whether you have continuous exclusive access to 
this file, from the time it is opened to the time it is closed. This option 
often is used when performing some critical operation, such as updating 

the file. 

01 = Exclusive access. After this file is opened, prohibits another 
FOPEN request, whether issued by this or another process, until 
this process issued the FCLOSE request or terminates. If any 
process already is accessing tnis me wucn u«s *^— ^ — - ~ 
issued, a CCL error code is returned to the calling process. If 
another FOPEN call is issued for this file while the exclusive 
aoption is in effect, an error code is returned to that calling 
process. The exclusive access aoption can be requested only by 
users allowed the file locking access mode by the security 
provisions for the file. 
10 = Semi-exclusive access. After the file is opened, prohibits con- 
current output access to this file through another FOPEN request, 
whether issued by this or another process, until this process issues 
the FCLOSE request or terminates. A subsequent request for the 
input/output or update aoption access type will obtain read only 
access. Other types of read access, however, are allowed. If any 
process already has output access to the file when this FOPEN call 
is issued, a CCL error code is returned to the calling process. If 
another FOPEN call that violates the read-only restriction is issue~ 
while the semi-exclusive aoption is in effect, that call fails and an 
error code is returned to the calling process. The semi-exclusive 
access can be requested only by users allowed the file-locking 
access mode by the security provisions for the file. 
11 = Share access. After the file is opened, permits concurrent access to 
this file by any process, in any access mode, subject to other basic 
MPE security provisions in effect. 
00 = Default value. If the read access only aoption is selected, share 
access (11) takes effect. Otherwise, exclusive access (01) takes 
effect. Regardless of which access is selected, FGETINFO will 
report 00. 
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Bit (7:1) — Inhibit Buffering Aoption. 

When selected, this aoption inhibits automatic buffering by MPE and 
allows input/output to take place directly between the user's data area 
and the applicable hardware device. 

= Allow normal buffering. 

1 = Inhibit buffering (NOBUF). 

NOBUF access is oriented to the transfer of physical blocks rather than 
logical records. 

With NOBUF access, you have responsibility for blocking and de- 
blocking of records in the file (see Section III). To be consistent with 
files built using buffered I/O, records should begin on word boundaries, 
and when the information content of the record is less than the defined 
record length, the record should be padded with blanks by you if the 
file is ASCII or with zeros if the file is binary. 

The recsize and block size for files manipulated under NOBUF access 
follow the same rules as those files that are created using buffering. The 
default blockfaetor for a file created under NOBUF is one. 

When a NOBUF file is opened without multirecord access, the amount 
of data transferred per read or write is limited to a maximum of one 
block. 

The end-of-file, next record pointer, and record transfer count are 
maintained in terms of logical records for all files. The number of 
logical records affected by each transfer is determined from the size of 
the transfer. 

Transfers always begin on a block boundary. Those transfers which do 
not transfer whole blocks leave the next record pointer set to the first 
record in the next block. The end-of-file pointer always points at the 
last record in the file. 

For files opened with NOBUF access, the FREADDIR, FWRITEDIR, 
and FPOINT intrinsics treat the recnum parameter as a block number. 

Non-RIO access to a RIO file can be indicated by specifying the 
NOBUF option. In this case the physical blocksize (item #21) from 
FFILEINFO should be used to determine the maximum transfer length. 
(The FGETINFO "blksize" parameter may also be used.) 

Bits (5:2) — Multi- Access Mode Aoption 

This feature permits processes located in different jobs or sessions to 

open the same file. 

00 - No multi-access. 

01 - Only intra-job multi-access allowed; this is the same as specifying 
the MULTI option in a FILE command. 

10 - Inter-job multi-access allowed; this is the same as specifying the 
GMULTI option in a FILE command. 

11 - Undefined. If this is specified, the FOPEN will be rejected with an 
error code of 40: ACCESS VIOLATION. 
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Bit (4:1) - No-Wait I/O Aoption. 

The selection of this aoption allows you to initiate an I/O request and 
to have control returned before the completion of the I/O. The IOWAIT 
intrinsic must be called after each I/O request to confirm the comple- 
tion of the I/O. The No-Wait I/O aoption implies the NOBUF aoption; 
if you do not specify NOBUF, the file system does it for you. Also, 
multirecord access is not available. This option is not available if the file 
is located on a remote computer. 

NOTE 

You must be running in Privileged Mode to use No-Wait 
I/O and NOBUF. 

Bits (3:1) — File Copy Aoption 

This feature permits any file to be treated as a standard sequential file, 

rather than as a file of its own type. 

- The file will be accessed in its native mode; that is, a message file 
will be treated as a message file, a KSAM file as a KSAM file, etc. 

■H ml f»»l _ • J _ 1.* 4-*m*~4- s- j4 — j~ — — i-— — aJ— i'S- J nAMiinw4-ifi1 -Wirt «T^+l^ TTAW1 n Kl ft^ 

i - ine iue is to oe treated, as a suanuaiu, sequcni/nu mc Aim »anauid- 

length records. 
Note: In order to access a message file in copy mode, a process must 
have exclusive access to the file. 

Bits (0:3) — Reserved for MPE. Should be set to zero. 

Default: All bits are set to zero. 

recsize integer by value (optional) 

An integer indicating the size of the logical records in the file. If a 
positive number, this represents words; bytes are represented by a nega- 
tive number. If the file is a newly-created file, this value is recorded 
permanently in the file label. If the records in the file are of variable 
length, this value indicates the maximum logical record length allowed. 

Binary files are word oriented. A record size specifying an odd byte 
count for a binary file is rounded up by FOPEN to the next highest 
even number. 

ASCII files may be created with logical records which are an odd num- 
ber of bytes in length. Within each block, however, records begin on 
word boundaries. 

For either ASCII or binary files with fixed or undefined length records, 
the record size is rounded up to the nearest word boundary. For exam- 
ple, a recsize specified as -106 for an ASCII file is 106 characters (53 
words) in length. A recsize of -113 for a binary file is 114 characters 
(57 words) in length. The rounded sizes should be used in computations 
for blockf actor or block size. 

When a foreign disc is opened, recsize is forced to 128 words. (Note: 
IBM diskettes are forced to 64 words.) 

Default: The default value is the configured physical record width of 
the associated device. 
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To specify density when writing to the tape files, the keyword "DEN=" 
is used. The DEN keyword must be preceded by a semicolon (;), which 
indicates to the system that a keyword follows. Note that if the device 
parameter is specified, a semicolon must terminate the device string. If 
device is not specified, then a semicolon must be the first character of 
the device parameter. The keyword string must be terminated by a 
carriage return. 

The density keyword is applicable only when writing to tape. When 
reading from a tape, the density selected by the user at FOPEN time 
will be ignored. For example, when reading from a tape, a 1600 BPI 
tape will satisfy an FOPEN request which specified ";DEN=6250", and 
vice -versa. The following examples show the correct syntax for the 
DEN= keyword: 

BYTE ARRAY DEVICE(0:13):="TAPE;DEN=6250",%13; 
BYTE ARRAY DEVICE(0:8):=";DEN=6250",%13; 



» 
NUM : = FOPEN (FILEX ,%4,%4„ DEVICE ) ; 

For more information on density selection, see Density Selection on 
Labeled and Unlabeled Tapes in Section X. 

If you are opening a 2680 page printer, you may specify an optional 
printing environment for your job. The printing environment is defined 
as all of the characteristics of the printed page which are not part of 
the data itself, and thus would include the page size, the margin width, 
the character set, the orientation (horizontal or vertical), and the name 
of any forms you wish to use. Such information is contained in the 
environment file. 

If you do not specify an environment file, FOPEN assumes that you 
warn, to use uie uemuii jjxihucj. cuvuuumcu>. i.**. ^iw.i^~ u «. *»«.... — * — 
prepared environment files, which reside in the ENV2680A group of 
the SYS account. For information on how to build your own printing 
environments, see the IFS/3000 manual, part number 36580-90001. 

To specify your own printer environment, you must also assign a key- 
word, ENV=, followed by the name of your environment file, to the 
device array, in the form, ENV= environment filename, and terminate 
the array with a carriage return. You must also include a semicolon 
between the device class name and the ENV keyword. For example, 
if PP is the device class name configured for your 2680 printer, 
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EQUATE CR =13; 

BYTE ARRAY DEVICE(0:50) :="PP;ENV=MYENVFLE",CR: 



NUM :=FOPEN (FILEX,%4,%4„DEVICE); 

Any environment you select remains active until replaced by a new en- 
vironment or until you FCLOSE the printer. If the printer has been 
opened with the multi-access AOPTION (e.g. as $STDLIST), a selected 
environment remains active until replaced or until the final FCLOSE of 
the printer. 

Default: DISC. 

formmsg byte array (optional) 

Contains a forms message that can be used for such purposes as telling 
the console operator what type of paper to use in the line printer. This 
message must be displayed to the operator and verified before this file 
can be printed on a line printer. The message itself is a string of ASCII 
characters terminated by a period. The maximum number of characters 
allowed in the array is 49, including the terminating period. Arrays with 
more than 49 characters are truncated by MPE. 
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device 



byte array (optional) 

Contains a string of ASCII characters terminating with any non-alpha- 
numeric character except a slash or period, designating the device on 
which the file is to reside, and optionally specifying density for tape 
files (DEN = parameter), and/or environment file for the 2680 page 
printer (ENV = parameter). This parameter may be specified in one of 
the following forms: 
devclass 

Idn 

* 

*vcname 
**volname 

The devclass form represents a device class name of up to eight alpha- 
numeric characters beginning with a letter, as for example, DISC or 
TAPE. If devclass is specified, the file is allocated to any available de- 
vice in that class. If you are opening a file which is to reside on a private 
volume, you must specify device class DISC; the file then is allocated to 
any of the home volume set's volumes that fall within that device class. 

The logical device number (Idn) consists of a three-byte numeric string 
specifying a particular device. If you are opening a file which is to re- 
side on a private volume, you must specify a disc drive on which one of 
the volumes in the home volume set resides. 

If you open a foreign disc file, device must be either a foreign disc class 
name or the Idn of a disc in a foreign disc class. When opening a foreign 
disc by logical device, the disc should be mounted on the drive, prior to 
the FOPEN. Otherwise it may be assumed to be a serial disc by the 

system. 

The forms *, *vcname, and **volname are used only if you are opening 
a file which is to reside on a private volume. 

If * is specified, the file is allocated to any of the volumes of the home 
volume set. 

If *vcname (volume class name) is specified, vcname must be a member 
of the home volume set. The file then is allocated to any of the volumes 
within the volume class. 

If **volname (volume name) is specified, volname must be a member of 
the home volume set. The file then is allocated to that volume. 

Any of the forms may be used to reference files on a remote computer 
by preceding the device or volume specification with DSDEVICE#. 
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This array also is used for tape label information if bit 6 of the f options 
parameter is set. The 49-character limit does not apply in this case. The 
tape label information is formatted as follows: 

^[volumeid] [,type] [,expdate] [,seq]; 

where 

volumeid - Consists of six or fewer printable characters that identify 
the volume. In a multi-volume set, only the first volumeid can be 
specified. 

type - Three alphabetic characters that identify label type information. 
Options are: 



blockfactor 



ANS - ANSI standard labels. (Default) 
IBM - IBM standard labels. 

expdate - Month/day /year of the expiration date of the file or the date 
after which the information contained in the file is no longer useful. 
The file can be overwritten after this date. Default is 00/00/00, mean- 
ing that the file can be overwritten immediately. In a volume set, file 
expiration dates must always be equal to or earlier than the date on the 
previous file. 

seq - Up to four characters that denote the position of the file in 
relation to other files on the tape. Default is "NEXT." A zero will 
cause a search of all volumes until file is found. If seg='ADDF," then 
the tape will be positioned to add a new file on the end of the volume 
or last volume in a multi-volume set. If seq= NEXT, then the tape will 
be positioned to the next file on the tape. If this is the first FOPEN, 
then NEXT will cause the tape to be positioned to the first file on the 
tape. If the previous FCLOSE specified REWIND backspace to last file. 
The position will remain as it was on the previous file. (You cannot 
append a file on a labeled tape.) 

.'ui/i/^/rn Lai iia!h/1 /rt»tfl/>*l/Tl I 

An integer specifying the number of user-label records to be written for 
this file. Applicable to new disc files only. The maximum number of 
user labels allowed varies from file to file. It depends on the final 
blockfactor and recsize used, as well as whether you have specified 
fixed, variable or undefined length records. If you specify more user 
labels than will fit in the 254 sectors following the MPE file label, an 
error occurs and the FOPEN fails. 

Default: The default number of user-label records is zero. 

integer by value (optional) 

An integer containing tne size ui uie uuua u«j u<= c&muuouw ^.~~ -...- - — , 
specified as a number equal to the number of logical records per block. 
For fixed-length records, blockfactor is the actual number of records in 
a block. For variable-length records, blockfactor is interpreted as a 
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multiplier used to compute the block size (maximum reesize x block- 
factor). For undefined-length records, blockfactor is always one logical 
record per block. The blockfactor value specified by you may be over- 
ridden by MPE. The valid range for blockfactor is from 1 through 255. 
Specification of a negative or zero value results in the default block- 
factor setting. Values greater than 255 are defaulted to 255. Blockfactor 
establishes the physical record size on disc and magnetic tape files. 

The blockfactor for foreign disc files is > = 1. 

Default: Calculated by dividing the specified reesize (in words) into the 
configured blocksize. This value is rounded downward to an integer 
that is never less than 1. 



numbuffers 



filesize 



integer by value (optional) 

A 16-bit word whose bits specify the following: 

Bits (11:5) - Number of Buffers. 

Specifies the number of buffers to be allocated to the file. This param- 
eter is not used for files representing interactive terminals, because a 
system-managed buffering method is always used in such cases. If 
omitted, set to zero, or set to a negative number, the default value of 2 
is set by MPE. 

Bits (4:7) — Number of Copies. 

For spooled output devices, specifies the number of copies of the entire 
file to be produced by the spooling facility. This can be specified for a 
file already FOPENed (for example, $STDLIST), in which case the high- 
est value supplied before the last FCLOSE will take effect. The copies 
do not appear contiguously if the console operator intervenes or if a 
file of higher outputpriority becomes READY before the last copy is 
complete. This parameter is ignored for non-spooled output devices. 
The default value is 1. 

Bits (0:4) — Output Priority. 

Specifies the outputpriority to be attached to this file. This priority is 
used to determine the order in which files are produced when several 
are waiting for the same device. This parameter must be a number be- 
tween 1 (lowest priority) and 13 (highest priority), inclusive. If this 
value is less than the current output fence set by the console operator, 
file printing/punching is deferred until the operator raises the output- 
priority of the file or lowers the output fence. This parameter can be 
specified for a file already FOPENed (for example, $STDLIST), in 
which case the highest value supplied before the last FCLOSE takes 
effect. This parameter is ignored for non-spooled devices. The default 
value is 8. 
Default: The default values of all bit groupings are taken. 

double by value (optional) 

A double-word integer (as defined in SPL) specifying the maximum file 
capacity in terms of blocks for files containing variable-length and 
undefined-length records, and logical records for files containing 
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numextents 



initialloc 



filecode 



fixed-length records. A zero or negative value results in the default 
filesize setting. The maximum capacity allowed is over two million 
(2 21 ) sectors. The number of sectors in a file is found by the formula 
shown under FILE CHARACTERISTICS in Section X. 

The filesize for foreign disc files is set to the maximum physical size of 
the disc as determined by its subtype. 

Because of spare tracks, remapped tracks, etc., the logical size will 
usually be smaller than the physical size. 
Default: 1 023 logical records. 

integer by value (optional) 

An integer specifying the maximum number of extents (integral number 
of contiguously-located disc sectors) that can be dynamically allocated 
to the file as logical records are written to it. The size of each extent 
is always calculated in terms of physical records. When the file is type F 
(fixed) filesize is the number of logical records; thus it will be divided 
by the blockf actor to determine the number of physical records (blocks). 
If the file is variable length or undefined length, filesize is the number 
of physical records. Then, the number of physical records required for 
the system file label, and user labels (if any), are added to the number 
of physical records required for data. To determine extent size, the 
number is divided by the requested numextents. The result rounded up, 
is the number of physical records per extent. This is then used to 
determine the actual number of extents and the size of each. If speci- 
fied, numextents must be an integer from 1 to 32. A zero or negative 
value results in the default setting. Any value >32 will automatically be 
set to 32. 
Default: 8 extents. 

NOTE 

Extents are allocated on any disc in the device class specified 
in the device parameter when the file was created. If it is 
necessary to insure that all extents of a file are on a particular 
j: „ „™«i« ^cr. Antrir-n niacc r>r a lncriral device number must 

be used in the device parameter. 

integer by value (optional) 

An integer specifying the number of extents to be allocated to the file 

when it is opened. This must be an integer from 1 to 32. If an attempt 

to allocate the requested disc space fails, the FOPEN intrinsic returns 

an error condition code to the calling program. 

Default: 1 extent. 

integer by value (optional) 

An integer recorded in the file label and made available for general use 
to anyone accessing the me tnrougn me rujunifu mumum.. i->» "— 
parameter, any user can specify a positive integer ranging from to 
1023. This parameter is used for new file:, only when it is positive and 
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the process is running in user mode. If your process is running in 
privileged mode, you can specify a negative integer for filecode when 
initially opening a file. Then, any future accesses of the "privileged" file 
must be requested in privileged mode. A process running in user mode 
cannot open a file that has a negative filecode. Also, if the process 
supplies a non-zero parameter the filecode must match the one 
originally specified for the file. Certain integers have particular 
HP-defined meanings, as follows: 



Mnemonic 


Integer 


Meaning 


USL 


1024 


USL file. 


BASD 


1025 


BASIC data file. 


BASP 


1026 


BASIC program file. 


BASFP 


1027 


BASIC fast program file. 


RL 


1028 


RL file. 


PROG 


1029 


Program file. 


SL 


1031 


SL file. 


VFORM 


1035 


VIEW formsfile. 


VFAST 


1036 


VIEW fast forms file. 


XLSAV 


1040 


Cross Loader ASCII file (SAVE). 


XLBIN 


1041 


Cross Loader relocated binary file. 


XLDSP 


1042 


Cross Loader ASCII file (DISPLAY) 


EDITQ 


1050 


Edit KEEPQ file (non-COBOL). 


EDTCQ 


1051 


Edit KEEPQ file (COBOL). 


EDTCT 


1052 


Edit TEXT file (COBOL). 


RJEPN 


1060 


RJE punch file. 


QPROC 


1070 


QUERY procedure file. 




1071 


QUERY work file. 




1072 


QUERY work file. 


KSAMK 


1080 


KSAM key file. 


LOG 


1090 


User Logging logfile. 



Integer 



Meaning 



1051 
1052 
1060 
1069 
1070 

1071 i 

1072 J 
1080 
1090 
Default: 



An EDIT KEEPQ file (COBOL). 

An EDIT TEXT file (COBOL). 

An RJE punch file. 

Reserved. 

A QUERY procedure file. 

QUERY work files. 

KSAM Key file. 

User Logging 



0. 
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CONDITION CODES 

CCE Request granted. The file is open. 

CCG Not returned by this intrinsic. 

CCL Request denied. This may be because another process already has 

exclusive or semi-exclusive access for this file, or an initial allocation of 
disc space cannot be made due to lack of disc space. The file number 
value returned by FOPEN if the file is not opened successfully is zero. 
The FCHECK intrinsic should be called for more details. 

TEXT DISCUSSION 

Page 10-27 



2-93 



FPOINT 



INTRINSIC NUMBER 6 Sets the logical record pointer for a disc file. 



IV DV 
KI'OT N I ( fUrmim.rccnum ) ; 



The FPOINT intrinsic sets the logical record pointer for a disc file, containing fixed-length or 
undefined records, to any logical record in the file. When the next FREAD or FWRITE request is 
issued for the file, this record will be the one read or written. 

PARAMETERS 

filenum integer by value (required) 

A word identifier supplying the file number of the file on which the 
pointer is to be set. 

recnum double by value (required) 

A positive double integer representing the relative logical record (or 
block number of NOBUF files) at which the logical record pointer is to 
be positioned. The number of the first logical record is zero. 

NOTE 

On disc files, the end-of-file indicator is the file limit. Magnetic 
tape files are delimited by the end-of-file marker. 

CONDITION CODES 

CCE Request granted. 

CCG Request denied. The logical record pointer position is unchanged. 

Positioning was requested at a point beyond the file limit. 

CCL Request denied. The logical record pointer position is unchanged 

because of one of the following: 
recnum was <0. 
Invalid filenum parameter. 

Input/output is pending on a no -wait I/O request. 
The file is spooled or is not on disc. 

The file does not contain fixed -length or undefined -length records. 
Not allowed with append access. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Page 10-91 
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Reads a logical record from a file on any INTRINSIC NUMBER 2 

device to the user's stack. 



I IV LA IV 

tgth:=WnEADifilemtm r target,tcaun{); 

The FREAD intrinsic reads a logical record, or a portion of such a record, from a file on any device 
to the user's stack. The record read is determined by the current position of the record pointer. 

When the logical end-of-data is encountered during reading, the CCG condition code is returned to 
the user process. On magnetic tape, the end-of-data can be denoted by a physical indicator such as 
a tape mark. When a file is read that spans more than one volume of labeled magnetic tape, the 
user program is suspended until the operator has completed mounting the next tape. CCG is not 
returned when end-of-tape is encountered. On disc, the end-of-data occurs when the last logical 
record of the file is passed. In this case, the CCG condition code is returned and no record is read. 
If the file is embedded in an input source containing MPE commands, the end-of-data is indicated 
when an :EOD command is encountered, but the :EOD command itself is not returned to the user. 
The end-of-data is indicated by a hardware end-of-file, including :EOF:, or on $STDIN by any 
record beginning with a colon, or on $STDINX by :EOD. In addition, on the standard input device 

•P«« «. i^K rtn Ar>r\/\cA/1 +-.<-* j» eogoirtw • TOR -T7fVT f\r *T\ ATA inrHr»*afc» onH.nf-Hnt.fl 
X.KJL a juu, cio wJ-zJ-'wo'cva uu a. ocokjiwn, .uv^j-»j .AJwe», vj-j. •wriii4 ui\«^uw v.**.w \js,~^m. *-.~o.. 



When an old file containing carriage-control characters, supplied through the control parameter of 
the FWRITE intrinsic, is read, and the carriage-control foption parameter of the FOPEN intrinsic, 
or the CCTL parameter of the :FILE command is specified, the carriage-control byte is read as 
follows : 

DATA READ 



CARRIAGE 
CONTROL 

BYTE-^ 

(If file has carriage control specified.) 

FUNCTIONAL RETURN 

The FREAD intrinsic returns a positive integer value showing the length of the information trans- 
ferred. If the tcount parameter in the FREAD call was positive, the positive value returned repre- 

senis a wuru uuuiit; 11 uie icuurn pcucuiiei/ei wao negative, me puoiuvc nuuc n,tuincu iopvovu» •* 

byte count. FREAD always returns zero if no-wait I/O is specified. In this case, the actual record 
length is returned in the tcount parameter of the 10 WAIT intrinsic. 

PARAMETERS 

filenum integer by value (required) 

A word identifier supplying the file number of the file to be read. 

target logical array (required) 

An array to which the record is to be transferred. This array should be 
large enough to hold all of the information to be transferred. 
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tcount integer by value (required) 

An integer specifying the number of words or bytes to be transferred. 
If this value is positive, it signifies the length in words; if it is negative, 
it signifies the length in bytes; if it is zero, no transfer occurs. If tcount 
is less than the size of the record, only the first tcount words or bytes 
are read from the record. 

If tcount is larger than the size of the logical record, and the multi- 
record aoption was not specified in FOPEN, transfer is limited to the 
length of the logical record. If the multirecord aoption was specified 
in FOPEN, transfer continues until either tcount is satisfied or the end- 
of-data is encountered, and each transfer will begin at the start of the 
next physical record (i.e., block). Any data remaining in the last physi- 
cal record read will be inaccessible. 

CONDITION CODES 

CCE The information was read. 

CCG The logical end-of-data was encountered during reading. When reading a 

labeled magnetic tape file that spans more than one volume, CCG is not 
returned when end-of-tape (EOT) is encountered. Instead, CCG is re- 
turned at actual end-of-file, with a transmission log of if an attempt is 
made to read past end-of-file. 

CCL The information was not read because an error occurred, a terminal 

read was terminated by a special character or timeout interval as speci- 
fied in the FCONTROL intrinsic, or a tape error was recovered and the 
FSETMODE option was enabled. 

NOTE 

The condition codes should be checked both in normal I/O 
and in no-wait I/O. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Page 10-47 
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Reads a logical recuixi ucginning au a pouu 
prior to the current record pointer. 
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Igth :-KRE ADBACKWA RlXfilenumJargettcount); 

The FREADBACKWARD intrinsic reads a logical record from a tape to the user's stack. The record 
read is determined by the current position of the record pointer. This intrinsic permits access to the 
Read Reverse capability of HP -IB Magnetic Tape Drives, and can be used to recover tape errors 
when handling I/O management and data recovery routines. 

Presently two substantial restrictions are associated with the use of this intrinsic: 

1. It may only be used with Magnetic Tape Drives on HP-IB Systems (i.e., Series 30, 33, 44, and 
Series III with HP -IB Interface Module). 

2. The magnetic tape must be accessed NOBUF. 

FUNCTIONAL RETURN 

mi T-iT-*T-t * t-*t^ a *-it7"*"It a tjt-\ • _ J.™-— ~; ~ « A i. ir v.n « «^fii+«T£s i*-*+o<*p-i* Trpliip cVi/vwrincf +:T"i P lpricrnn nf trip inTOT*- 
TJie J? J&rjAJLADi\^iN.VV.tt.IVL; lXlurinSli: ±CLUrX±S a pubiuvc jaii^feCx vtU^C b»v«.m^ k— ~ -c«g«. w* , ^-- 

mation transferred. If the tcount parameter in the FREADBACKWARD call was positive, the 
positive value returned represents a word count; if the tcount parameter was negative, the positive 
value returned represents a byte count. FREADBACKWARD always returns zero if no-wait I/O is 
specified. In this case, the actual record length is returned in the tcount parameter of the IOWAIT 
intrinsic. 



filenum 
target 

tcount 



integer vy value (required) 

A word identifier supplying the file number of the file to be read. 

logical array (required) 

An array to which the record is to be transferred. This array should be 

large enough to hold all of the information to be transferred. 

integer by value (required) 

An integer specifying the number of words or bytes to be transferred. 
If this value is positive, it signifies the length in words; if it is negative, 
it signifies the length in bytes; if it is zero, no transfer occurs. If tcount 
is less than the size of the record, only the first tcount words or bytes 
are read from the record. 

If tcount is larger than the size of the logical record, and the multi- 
record aoption was not specified in FOPEN, transfer is limited to the 
length of the logical record. If the multirecord aoption was specified in 
FOPEN, transfer continues until either tcount is satisfied or the begin- 
ning-of-data is encountered, and each transfer will begin at the end of 
the next physical record (i.e., block). Any data remaining in the last 
physical record read will be inaccessible. 



JUL1981 
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CONDITION CODES 

CCE The information was read. 

CCG The logical beginning-of-data was encountered during reading. When 

reading a labeled magnetic tape file that spans more than one volume, 
CCG is not returned when beginning-of-tape (BOT) is encountered. 
Instead, CCG is returned at actual beginning of file, with a transmission 
log of if an attempt is made to read past beginning of file. 

CCL The information was not read because a tape error occurred, or a tape 

error was recovered and the FSETMODE option was enabled. 

NOTE 

The condition codes should be checked both in normal I/O 
and in no-wait I/O. 



SPECIAL CONSIDERATIONS 

Split stack calls permitted 

TEXT DISCUSSION 

None. 
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Keads a specific logical record from a disc file to the user's data stac~. 



INTRINSIC NUMBER 7 
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The FREADDIR intrinsic reads a specific logical record, or a portion of such a record, from a disc 
file to the user's data stack. This intrinsic differs from the FREAD intrinsic in that the FREAD 
intrinsic reads only the record pointed to by the logical record pointer. The FREADDIR intrinsic 
may be issued only for disc files composed of fixed-length or undefined-length records. If RIO 
access is used FREADDIR will input the specified logical record. If the record is inactive, the 
contents of the inactive record will be transmitted and a CCE will be returned. (FCHECK returns a 
non-zero error number to distinguish active and inactive records. If a RIO file is accessed using the 
non-RIO method, (NOBUF) FREADDIR will input the specified block. In this case there is no 
indication whether the block contains some inactive records. 

After the FREADDIR intrinsic is executed, the logical record pointer is set to the beginning of the 
next logical record, or first logical record of the next block for NOBUF files. 

It is possible to skip portions of records inadvertently if the multirecord aoption of FOPEN is set 
and the tcount parameter specified is greater than one logical record. For example, if you read all of 
record 11 and half of record 12 in a file, the logical record pointer is set to the beginning of record 
13 after the FREADDIR intrinsic executes. Thus the second half of record 12 may be skipped. 



PARAMETERS 

filenum 



integer by value (required) 

A word identifier supplying the file number of the file to be read. 



target 



logical array (required) 

An array to which the record is to be transferred. This array should be 

large enough to hold all of the information to be transferred. 



tcount 



recnum 



integer by value (required) 

An integer speciiying wie uuiuua ui «iui<*j >-"• ~jv~- 

this value is positive, it signifies words; if negative, it signifies bytes; and 
if it is zero, no transfer occurs. If tcount is less than the size of the 
record, only the first tcount words or bytes are read from the record. 

If tcount is larger than the size of the logical record and the multirecord 
aoption was not specified in FOPEN, the transfer is limited to the 
length of the logical record. If the multirecord aoption was specified in 
FOPEN, the remaining words or bytes specified in tcount are read from 
succeeding records. 

double by value (required) 

A double- word integer indicating the relative number, in the file, of the 
logical record to be read. The first record is indicated by OD (double 
word zero in SPL notation). 
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CONDITION CODES 

CCE The information was read. 

CCG End of file was encountered. 

CCL The information was not read because an error occurred. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Page 10-49 
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Reads a user file label, INTRINSIC NUMBER 19 

IV LA IV IV O-V 

The FREADLABEL intrinsic reads a user-defined label from a disc file or magnetic tape file. Once a 
disc file has been opened, user labels may be read from or written to regardless of the opener's 
access to the rest of the file. A disc file can have up to 254 128-word user labels. A magnetic tape 
file must be labeled with an ANSI-standard or IBM-standard label. Before reading occurs, the user's 
read access capability is verified. Note that MPE automatically skips over any unread user labels 
when the first FREAD intrinsic call is issued for a file, therefore, the FREADLABEL intrinsic should 
be called immediately after the FOPEN intrinsic has opened the file. If the file is on labeled magnetic 
tape, the user-defined label must be 40 words in length to conform to the length of the ANSI or 
IBM-standard label. Refer to Appendix D for the format of magnetic tape labels. 

PARAMETERS 

filenum integer by value (required) 

A word identifier supplying the file number of the file whose label is to 

be read. 

target logical array (required) 

An array in the stack to which the label is to be transferred. This array 
should be large enough to hold the number of words specified by 

tcount. 

tcount integer by value (optional) 

An integer specifying the number of words to be transferred from the 
label. Tcount is limited to 128 words. 
Default: 128 words. 

labelid integer by value (optional) 

An integer specifying the label number. 
Default: Zero is assigned. 

CONDITION CODES 

CCE The label was read. 

CCG Tne intrinsic referenced a label beyond the last label written on the file. 

CCL The label was not read because an error occurred. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Page 10-63 
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INTRINSIC NUMBER 12 Moves a record from a disc file to a buffer in anticipation 

of a FREADDIR intrinsic call. 



IV DV 



Direct access of disc files can be enhanced by issuing the FREADSEEK intrinsic call. This call is 
used when the need for a certain record is known before its transfer to the user's stack, by a 
FREADDIR call, is actually required. The FREADSEEK intrinsic directs MPE to move the record 
from disc into a buffer in anticipation of the FREADDIR call, which subsequently moves the 
record directly to the stack. 

NOTE 

The FREADSEEK intrinsic call can be issued only for files 
for which input/output buffering and fixed or undefined- 
length records are in effect. 

PARAMETERS 

filenum integer by value (required) 

A word supplying the file number of the file to be read. 

recnum double by value (required) 

A double- word integer in SPL notation indicating the relative number 
of the logical record to be read. The first record is indicated by OD. 

CONDITION CODES 

CCE Request granted. 

CCG A logical end-of-file indication was encountered. 

CCL Request denied because an error occurred. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Page 10-50 



2-102 



FREEDSEG 

r_i-„ x ., a a^z -e^ant INTRINSIC NUMBER 131 



LV LV 
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A process can release an extra data segment assigned to it by using the FREEDSEG intrinsic. If this 
is a private data segment, or if it is a sharable segment not currently assigned to any other process m 
the job/session, the segment is deleted from the entire job/session. Otherwise, it is deleted from the 
calling process but continues to exist in the job/session. 

PARAMETERS 

index logical by value (required) 

A word containing the logical index assigned to the data segment, 
obtained from the GETDSEG intrinsic call. 

Id logical by value (required) 

The identity, if any, assigned to the segment. If none is assigned, zero 

qVi/inlH ho pntpred. 

CONDITION CODES 

CCE Request granted. The data segment is deleted from the job/session. 

CCG Request granted. The data segment is deleted from the calling process 

but continues to exist in the job/session because it is being shared by 
another process. 

CCL Request denied. Either the index is invalid or index and id do not 

specify the same extra data segment. 

SPECIAL CONSIDERATIONS 

t^~j-~ a*™**™**- Tv/ToviQfT£iT-non+ Pa Tin hili tv rpnuired. 

TEXT DISCUSSION 

Page 8-15. 
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INTRINSIC NUMBER 31 Frees all local RIN's from allocation to a job. 

FREELOCRIN; 

The FREELOCRIN intrinsic frees all local Resource Identification Numbers (RIN's) currently 
reserved for your job. 

If the GETLOCRIN intrinsic has been called by a process, the FREELOCRIN intrinsic must be 
called before GETLOCRIN can be called successfully a second time. 

CONDITION CODES 

CCE Request granted. 

CCG Request denied because no RIN's are currently reserved for the job. 

CCL Request denied because at least one RIN is currently locked by a 

process. 

TEXT DISCUSSION 

Page 6-9. 
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Determines whether a file pair is interactive, duplicative, 
or both interactive and duplicative. 



FRELATE 

INTRINSIC NUMBER 18 
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A device file is interactive if it requires human intervention for all input operations. This quality is 
necessary to establish the person/ machine dialog required to support a session. A device file is 
duplicative if all input operations are echoed to a corresponding display without intervention by the 
operating system software. 

You can determine whether a pair of files is interactive, duplicative, or both interactive and 
duplicative through the FRELATE intrinsic call. The interactive /duplicative attributes of a file pair 
do not change between the time they are opened and the time they are closed. 

The FRELATE intrinsic applies to files on all devices. 

NOTE 

A condition code of CCG is returned when either infilenum 
or listfilenum corresponds to $NULL. $NULL is considered 
to be a logical file which contains no data. No data can be 
read from this file and all data written to it are discarded. 
The infilenum and listfilenum functions, therefore, are 
illogical for the $NULL file. 

FUNCTIONAL RETURN 

FRELATE returns a word to the calling process showing whether the two files referenced are 
interactive and/or duplicative. The word returned contains two significant bits, bit 15 and bit 1. 

If bit 15 = 1, infilenum and listfilenum form an interactive pair. 

If bit 15 = 0, infilenum and listfilenum do not form an interactive pair. 

if un = i infiiomjm and listfilenum form a duplicative pair. 

If bit = 0, infilenum and listfilenum do not form a duplicative pair. 

PARAMETERS 

infilenum integer by value (required) 

A word identifier supplying the file number of the input file. 

listfilenum integer by value (required) 

A word identifier supplying the file number of the list file. 

CONDITION CODES 

CCE Request granted. 
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CCG Request denied because infilenum and/or listfilenum corresponds to 

$NULL. Interactive or duplicative functions do not apply. 

CCL Request denied because an error occurred. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Page 10-92 
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Renames a disc file. 



INTRINSIC NUMBER 17 
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The FRENAME intrinsic changes the actual designator (including lockword, if any) of an open disc 
file. The home volume set of newfile reference must be the same as that of the file being renamed. 
(Volume sets cannot be spanned when renaming files.) 

The file to be renamed must be either: 

1. A new file, or . 

2 An existing file, opened for fully-exclusive access, for which you have write access (speci- 
fied by the security provisions of the file). If the file is a permanent file, you must be the 
creator. 



PARAMETERS 

fllenum 



tie wftlereference 



integer by value (required) 

A word identifier supplying the file number of the file to be renamed. 

byte array (required) 

Contains an ASCII string specifying the new name of the file. The 
maximum number of characters allowed in the string is 36. The format 
of newfilereference is 



filename /lockword.group.account 

where 

filename = the new file name for the file. (Required in 
newfilereference.) 

lockword = a lockword for the new file name. (Optional parameter of 
newfilereference.) If you wish to keep, or add a lockword 
to the file, you must enter the lockword parameter in the 
ASCII string. If this part of newfilereference is not 
specified, the new file named will not have a lockword 
associated with it. 



group 



= the group name where the file is to reside. (Optional 
parameter of newfilereference.) If no group is specified, 
the file will reside in the group to which it was assigned 
before the FRENAME intrinsic call. 



account = the account name where the file is to reside. (Optional 
parameter of newfilereference. ) The account to which the 
file is currently assigned must be used. If other than the 
current account name is specified, the CCL error condition 
is returned and the file retains its old name. 
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The ASCII string contained in newfilereference must begin with a 
letter; can contain up to eight alphanumeric characters for each of the 
filename, lockword, group, and account fields; and must end with any 
non-alphanumeric character, including a blank, other than a slash (/) or 
a period (since period and slash are used as field delimiters within the 
string). 



CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because an error occurred. 

TEXT DISCUSSION 

Page 10-43 
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Activates or deactivates file access modes. 



INTRINSIC NUMBER 14 
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The FSETMODE intrinsic activates or deactivates the following access mode options: automatic 
error recovery, critical output verification, and terminal control by the user. 

The access mode established by the FSETMODE intrinsic remains in effect until another 
FSETMODE call is issued or until the file is closed. The FSETMODE intrinsic applies to files on all 
devices. 



PARAMETERS 

filenum 



integer by value (required) 

A word identifier supplying the file number of the file to which the call 

applies. 



mode flags 






A 16-bit value that denotes the access mode options in effect, as 
described below. 

Bit (14-1) — Critical Output Verification 

1 = All physical (block) output to the file is to be verified as physically 
complete (when full data buffers are posted) before control returns 
from a write intrinsic to the user's program. The user waits while 
the system is posting a full block to the file. Note that this bit is 
effective only in buffered mode. 

= Output is not verified. 

Bit (13:1) — Terminal Control by the User 

1 = Inhibit normal terminal control by the system. Thus, MPE will not 

issue an automatic carriage return and line feed at the completion 
of each terminal input line. 

= MPE will automatically issue the carriage return and line feed for 

the terminal. This parameter is ignored if the device is not a 

tsrniin?.]. 
Carriage return, line feed is not issued in the case where FREAD file- 
num target, or tcount is satisfied (tcount characters are typed in). If 
carriage return is hit, however, a carriage return is echoed but no line 
feed is sent. This also applies to the READ intrinsic. 

Bit (12:1) — Tape Error Recovery 

1 = Report recovered tape error by FREAD or FWRITE with CCL 

™™rK+ion nnrifi and error number. 
= Report recovered tape error with CCE condition code. 

The remaining 13 bits are reserved for MPE and must always be set to 

zero. 
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CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because an error occurred. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Page 10-91 
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Spaces forward or backward on a file. INTRINSIC NUMBER 5 

IV IV 



You can space forward or backward on a fixed-length or undefined-length file by using the FSPACE 
intrinsic. This results in resetting the logical record pointer. The FSPACE intrinsic applies to files on 
disc and magnetic tape devices only. On magnetic tape devices, however, FSPACE spaces physical 
rather than logical records. 

The FSPACE intrinsic cannot be used with variable-length record files or with spooled files on disc. 
An attempt to use this intrinsic on such files results in a CCL error condition code and the logical 
record pointer is left at its current position. 

See Section III for special considerations on magnetic tape files. 

PARAMETERS 

plenum integer by value (required) 

A word identifier supplying the file number of the file on which spacing 
is to be done. 

displacement integer by value (required) 

A signed integer indicating the number of logical records for buffered 
disc files, or blocks for NOBUF files and all tape files, to be spaced 
over, relative to the current position of the logical record pointer. A 
positive value signifies forward spacing, a negative value signifies back- 
ward spacing. The maximum positive value is 32767, the maximum 
negative value is -32768. If RIO access is used, the displacement 
includes all records regardless of activity state (i.e., active deleted). 
Attempts to backspace beyond the beginning of the file will be ignored 
by the system. The logical record pointer will point to record ( the 
first record) and no error codes will be returned. 

CONDITION CODES 

CCE Request granted. 

CCG An end-of-file indicator was encountered during spacing. For disc files, 

this is the file limit, and the logical record pointer is not changed. For 
magnetic tape files, it is the end-of-file mark, and the logical record 
pointer points to the (logical) end-of-file. The magnetic tape, however, 
is positioned to one record past the file mark on the tape. For labeled 
tape the logical record pointer is at the file mark. 

CCL Request denied because an error occurred; for example file resides on a 

device that prohibits spacing. 
Not allowed with append access. 
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SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Page 10-89 
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Dynamically unlocks a file. 



INTRINSIC NUMBER 16 



IV 



The FUNLOCK intrinsic dynamically unlocks a file (Resource Identification Number) that has been 
locked with the FLOCK intrinsic. 



PARAMETERS 

plenum 



integer by value (required) 

A word supplying the file number of the file to be unlocked. 



CONDITION CODES 

CCE Request granted 

CCG Request denied because the file had not been locked by the calling 

process. 



CCL 



Request denied because the file was not opened with the dynamic 
locking aoption of the FOPEN intrinsic, or the filenum parameter is 
invalid. 



Split stack calls permitted. 

TEXT DISCUSSION 

Page 10-55 
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INTRINSIC NUMBER 4 Updates (writes) a logical record in a disc file. 

IV LA IV 
FU F- D \ r Eifilemtm, tar&s, tcount) ; 

The FUPDATE intrinsic updates a logical record in a disc file. This intrinsic affects the logical 
record (or block for NOBUF files) last referenced by any intrinsic call for the file named. 
FUPDATE moves the specified information from the user's stack into this record. The file 
containing this record must have been opened with the update aoption specified in the FOPEN call, 
and must not have variable-length records. If RIO access is used, the modified record is set to the 
active state. 

Note that FUPDATE is functionally equivalent (but faster) to FSPACE(FILENUM, -1); followed 
by an FWRITE to FILENUM. 

PARAMETERS 

filenum integer by value (required) 

A word identifier supplying the file number of the file to be updated. 

target logical array (required) 

Contains the record to be written in the updating. 

tcount integer by value (required) 

An integer specifying the number of words or bytes to be written from 
the record. If this value is positive, it signifies words; if it is negative, it 
signifies bytes; if it is zero, no transfer occurs. If tcount is less than the 
recsize parameter associated with the record, only the first tcount bytes 
or words are written. For buffered file, tcount is limited to the block 
size. FUPDATE cannot update more than one block in multirecord 
mode. 

CONDITION CODES 

CCE Request granted. 

CCG An end-of-file condition was encountered during updating. 

CCL Request denied because of an error, such as the file not residing on disc, 

or tcount exceeding the size of the block when multirecord mode is not 
in effect. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Page 10-57 
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Writes a logical record from the user's stack to a file on any device. INTRINSIC NUMBER 3 

IV LA IV LV 

The FWRITE intrinsic writes a logical or physical record, or a portion of such a record, from the 
user's stack to a file on any device. 

When information is written to a fixed-length record, and the NOBUF aoption was not specified in 
FOPEN, any unused portion of the record will be padded with binary zeros for a binary file or 
ASCII blanks for an ASCII file. 

When the FWRITE intrinsic is executed, the logical record pointer is set to the record immediately 
following the record just written, or the first logical record in the next block for NOBUF files. If 
RIO access is used, the modified record is set to the active state. 

When an FWRITE call writes a record beyond the current logical end-of-file indicator, this indicator 
is advanced to a farther location; however, this is only noted in the file label when the file is 
actually closed or when an extent is allocated. If the physical bounds of the file are reached, the 
CCG condition code is returned. 

If a magnetic tape is unlabeled (as specified in the FOPEN intrinsic or :FILE command) and a user 
program attempts to write over or beyond the physical EOT marker, the FWRITE intrinsic returns 
an error condition code (CCL). The actual data has been written to the tape, and a call to FCHECK 
reveals a file error indicating END OF TAPE. All writes to the tape after the EOT tape marker has 
been crossed transfer the data successfully but return a CCL condition code until the tape crosses 
the EOT marker again in the reverse direction (rewind or backspace). 

If a magnetic tape is labeled (as specified in the FOPEN intrinsic or :FILE command), a CCL condi- 
tion code is not returned when the tape passes the EOT marker. Attempts to write to the tape after 
the EOT marker is encountered cause end of volume (EOV) markers to be written. A message then 
is printed on the operator's console requesting another volume (reel of tape) to be mounted. 

PARAMETERS 

jiienuin nn.t. 6 oi uj w.«».~~ i . ~-i , 

A word identifier supplying the file number of the file to be written on. 

target logical array (required) 
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tcount integer by value (required) 

An integer specifying the number of words or bytes to be written to the 
record. If this value is positive, it signifies words; if it is negative, it 
signifies bytes; if it is zero, no transfer occurs. If tcount is less than the 
recsize parameter associated with the record, only the first tcount 
words or bytes are written. 

If tcount is larger than the logical record size and the NOBUF aoption 
is not specified in FOPEN, the FWRITE request is refused and condi- 
tion code CCL is returned. If NOBUF is specified, tcount may not 
exceed the physical record size unless the multirecord option is specified. 
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control 



If the multirecord aoption is specified in FOPEN, the excess words or 
bytes are written to succeeding physical records. For files for which 
carriage control is specified, the actual data transferred is limited to 
recsize minus one byte. 

logical by value (required) 

A logical value representing a carriage control code, effective if the file is 
transferred to a line printer or terminal (including a spooled file whose 
ultimate destination is a line printer or a terminal). This parameter is 
effective only for files opened with carriage control specified. 

The options are: 

— Print the full record transferred, using single spacing. This results 
in a maximum of 132 characters per printed line. 

1 — Use the first character of the data written to satisfy space control, 
and suppress this character on the printed output. This results in a 
maximum of 132 characters of data per printed line. Permissible control 
characters are shown in figure 2-3. 

Any octal code from figure 2-3 can be used to determine space control 
and print the full record transferred. This results in a maximum of 132 
characters per printed line. 

If the control parameter is not or 1, and tcount is 0, only the space 
control is executed — no data are transferred. 

The effect of the FWRITE control parameter in combination with the 
FOPEN carriage control f option (or overriding :FILE command CCTL/ 
NOCCTL parameter) upon the data written is summarized in figure 2-4. 

You determine whether the carriage control directive takes effect before 
printing (pre-space movement) or after printing (post-space movement), 
through the FCONTROL intrinsic. 

Sometimes it is necessary to set the pre-space/post space control and 
the auto/no auto page eject control with the FWRITE instead of 
FCONTROL. You may use control codes %100 through %103 and 
%400 through %403 for this. If you specify one of the above controls 
with + count = 0, no physical I/O will occur. 

All of the carriage control codes listed in figure 2-3 may be used as the 
value of the param parameter in FCONTROL (when controlcode=l), 
regardless of whether the file is opened with CCTL or NOCCTL. When 
the file is opened with CCTL, these carriage control codes may be used 
in either of the following ways via FWRITE: 

a. As the value of the control parameter. 

b. When control = 1, as the first byte of the target array. 

The default carriage control code is post spacing with automatic page 
eject. This applies to all HP -supported subsystems except FORTRAN 
which is prespacing with automatic page eject. 
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CONDITION CODES 



CCE 
CCG 

CCL 



OCTAL CODE 



%40 
%53 

%55 
%60 
%61 



%2nn (nn is any 
octal number 



Request granted. 

The physical bounds of the file prevented further writing; all disc 
extents are filled. 

Request denied because an error occurred, such as tcount exceeding the 
size of the record in non-multirecord mode; or the FSETMODE option 
is enabled to signify recovered tape errors; or the end-of-tape marker 
was sensed. If the file is being written to a multi-volume magnetic tape 
set, CCL is not returned when the end-of-tape marker is sensed. Instead, 
end-of-volume labels are written, and a request is issued to mount the 
next volume. 



ASCILSYMBOL 



"+' 



"0" 



CARRIAGE ACTION 



from through 




77) 




%300 - %307 




%300-%313 




%300-%317 





Single space (with or without automatic page eject). 

No space, return (next printing at column 1). Not valid on 2607/ 
2608 (results in single space without automatic page eject). 

Triple space (with or without automatic page eject).* 

Double space (with or without automatic page eject).* 

Page eject (form feed). Selects VFC Channel 1. Ignored if: 

Post-space mode: The current request has a transfer count of and 
the previous request was an FOPEN or FCLOSE or an FWRITE 
which specified a carriage-control directive of %61 . 

Pre-space mode: Both the current request and the previous request 
have transfer counts of 0, and the current request and previous re- 
quest are any combination of FOPEN, FCLOSE or an FWRITE speci- 
fying a carriage-control directive of %61 . 

Space nn lines (no automatic page eject). %200 not valid for 2607 
(results in single space without automatic page eject). 



Select VFC Channel 1-8 (2607) 

Select VFC Channel 1-12 (2613, 2617, 2618, 2619) 

Select VFC Channel 1-16 (2608) 



the resulting skip may be less than two or three lines, respectively. 

If automatic page eject is not in effect, a true double or triple space results, but the perforation between pages is not automatically 

skipped. 

Series ll/llf If these codes are selected with automatic page eject in effect, %60 and %61 are replaced by two or three %302 codes, 

respectively. This results in true double or triple spacing, and also skips the perforation. 



If automatic page eject is not in effect, the behavior is the same as for Series 30/33/44. 

Figure 2-3. Carriage-Control Directives (Sheet 1 of 2) 
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FWRITE 



OCTAL CODE 



%300 

%301 

%302 

%303 

%304 
%305 

%306 
%307 
%310 
%311 

%312 

%313 

%314 

%315 

%316 

%317 

%320 

%2 - %37 

%41 - %52 

%54 

%56 - %57 

%62 - %77 

%104-%177 

%310-%317 

%314-%317 

%321 - %377 

%400or%100 



%401 or%101 
%402or%102 
%403or%103 



ASCII SYMBOL 



(2607) 
(2613/17/18/19) 



CARRIAGE ACTION 



NOTE 
Channel assignments shown below are the HP standard 
defaults. 

Skip to top of form (page eject). 

Skip to bottom of form. 

Single spacing with automatic page eject. 

Skip to next odd line with automatic page eject. 

Skip to next third line with automatic page eject. 
Skip to next 1/2 page. 

Skip to next 1/4 page. 

Skip to next 1/6 page. 

Skip to bottom of form. 

User option (2613/17/18/19), skip to one line before bottom of form 
(2608) 

User option (2613/17/18/19), skip to one line before top of form 
(2608) 

User option (2613/17/18/19), skip to top of form (2608) 

Skip to next seventh line with automatic page eject. 

Skip to next sixth line with automatic page eject. 

Skip to next fifth line with automatic page eject. 

Skip to next fourth line with automatic page eject. 

No space, no return (next printing physically follows this). 



Same as %40 



Sets post-space movement option; this first prints, then spaces. If 
previous option was pre-space movement, the driver outputs a line with 
a skip to VFC channel 3 to clear the buffer. 

Sets pre-space movement option; this first spaces, then prints. 

Sets single-space option, with automatic page eject (60 lines per page). 

Sets single-space option, without automatic page eject (66 lines per 
page). 



2-118 



Figure 2-3. Carriage-Control Directives (Sheet 2 of 2) 



FOPEN 

OR 
:FILE 



Carriage 

Control 

Foption 

Specified 

or 

CCTL 



Byte 
1 



recsize 
- 133 - 



record =1 32 



Carriage 

Control 

Foption 

not 

specified 

or 

NOCCTL 



Data output contains 
132 characters; the 
prefix byte is added 
and contains 



H- 



-132. 



record = 132 



Data output contains 
132 characters. 



FWRITE 



FWRITE Control Parameter 



recsize 
. 132 - 



record = 1 32 



Data output contains 
132 characters; the 
carriage control 
character in the first 
byte is not printed if 
output is to a list 
device. 



= Greater than 1 



Byte 
1 



h> 



recsize 
- 133 - 



-H 



con- 
trol 



record =132 



« 13° 


-■■ 




I 
record = 1 32 




- 



Data output contains 
132 characters 



Data output contains 
1 32 characters; the 
prefix character added 
is a carriage-control 
character specified by 
the FWRITE control 
parameter. 



EFFECT ON DATA OUTPUT 



Figure 2-4. Carriage-Control Summary 



SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Page 10-49 





13° 










record = 132 









Data output contains 
132 characters. 
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FWRITEDIR 



INTRINSIC NUMBER 8 



Writes a specific logical record from the user's stack to a disc file. 



IV LA IV DV :<-■ 
FWRlTEDIR(filenum.target. tcountjeertum ) ; 

The FWRITEDIR intrinsic writes a specific logical record (or physical record if NOBUF is specified), 
or a portion of such a record, from the user's stack to a disc file. This intrinsic differs from the 
FWRITE intrinsic in that the FWRITE intrinsic writes only the record pointed to by the logical 
record pointer. The FWRITEDIR intrinsic may be used only for disc files composed of fixed or 
undefined-length records. 

When information is written to a fixed-length record and NOBUF was not specified in the FOP EN 
call that opened the file, any unused portion of the record will be padded with binary zeros for a 
binary file, or ASCII blanks for an ASCII file. 

When the FWRITEDIR intrinsic is executed, the logical record pointer is set to the record 
immediately following the record just written, or the first logical record of the next block for 
NOBUF files. 

If RIO access is used, the modified record is set to the active state. 

When an FWRITEDIR call writes a record beyond the current logical end-of-file indicator, the 
indicator is advanced to a farther location. This can result in the creation of dummy records to pad 
the records between the previous end-of-file and the newly-written record. These dummy records 
are filled with binary zeros for a binary file, or with ASCII blanks for an ASCII file when the new 
record is in the same extent. 

When the physical bounds of the file prevent further writing, because all allowable extents are filled, 
the end-of-file condition (CCG) is returned to the user's program. 



PARAMETERS 

filenum 



target 



tcount 



integer by value (required) 

A word identifier specifying the file number of the file to be written 

on. 

logical array ( required) 

Contains the record to be written. This array should be large enough to 

hold all of the information to be transferred. 

integer by value (required) 

An integer specifying the number of words or bytes to be written to the 
record. If this value is positive, it signifies words; if it is negative, it 
signifies bytes; if it is zero, no transfer occurs. If tcount is less than the 
recsize parameter associated with the record, and NOBUF was specified, 
only the first tcount words or bytes are written. 

If tcount is larger than the size of the logical record and the NOBUF 
aoption was not specified in FOPEN, the transfer is limited to the 
length of the logical record. If NOBUF was specified and if tcount is 
larger thatn the size of the physical record, the transfer is limited to the 
length of the physical record if the multirecord aoption was not specified. 
If the multirecord aoption was specified in FOPEN, the remaining 
words or bytes are written to succeeding physical records up to the 
file limit. 



2-120 



FWRITEDIR 

recnurn double by value (required) 

A double integer indicating the relative number of the logical record, or 
block number for NOBUF files, to be written. The first record is 
indicated by OD. 

CONDITION CODES 

CCE Request granted. 

qqq The physical end-of-file was encountered. 

CCL Request denied because an error occurred. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Page 10-51 
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FWRITELABEL 



INTRINSIC NUMBER 20 Writes a user file label. 

iv la iv iv o-v :: 

FWMTELmM J (filettttnt > target,tcouM,Iabetid); 

The FWRITELABEL intrinsic writes a user-defined label onto a disc file or labeled magnetic tape 
file that is labeled with an ANSI-standard or IBM-standard label. This intrinsic overwrites old user 
labels. Once a disc file has been opened, user labels may be read from or written to regardless of the 
user's access to the rest of the file. If the file is on labeled magnetic tape, the user-defined label must 
be 40 words in length to conform to the length of the ANSI or IBM-standard label. Refer to 
Appendix D for the format of magnetic tape labels. 

PARAMETERS 

filenum integer by value (required) 

A word identifier specifying the file number of the file to which the 
label is to be written. 

target logical array (required) 

Contains the label to be written. If the file is a labeled magnetic tape 
file, this label must be 40 words in length. 

tcount integer by value (optional) 

An integer specifying the number of words to be transferred from the 

array. 

Default: 128 words. 

labelid integer by value (optional) 

An integer specifying the number of the label to be written. The first 

label is 0. 

Default: Zero is assigned. 

CONDITION CODES 

CCE Request granted. 

CCG Request denied because the calling process attempted to write a label 

beyond the limit specified in FOPEN when the file was opened. 

CCL Request denied because an error occurred. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Page 10-62 
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GENMESSAGE 



Accesses message system. 



m 






l IV (V IV BA 

msgteu;=GENMESSAGE(i?/«ia.-n,st'?««m..»?«g»M.'?J, 

LV LV LV LV LV IV I 0-V 

parml,parm2.p<trm3.parm4,parm5.msgdest,ermum); 

The GENMESSAGE intrinsic accesses the MPE message system. A message number is passed by 
GENMESSAGE to the message system. The message system fetches the message from a message 
catalog (opened by the calling program), inserts parameters supplied by GENMESSAGE into the 
message, then routes the message to a file or returns the message to the calling program. (If msg- 
dest is specified, the message is routed to a file. If buff is specified, the message is returned. If both 
msgdest and buff are specified, the message is both routed to a file and returned.) 

NOTE 

The catalog file must be opened with foptions old, permanent, 
ASCII (foptions 5), and aoptions nobuf and multi-record 
access (aoptions %420). 

FUNCTIONAL RETURN 

The length of the message is returned (in positive bytes) to msglen. 

PARAMETERS 



filenum 



setnum 



msgnutn 



buff 



buff size 



parmask 



integer by value (required) 

A word identifier supplying the file number of the message catalog. 

integer by value (required) 

A positive integer no greater than 62 specifying the message set number 

within the catalog. 

A positive integer, specifying the message number within the message 
set. 

byte array (optional) 

A byte array to which the assembled message is returned. 

Default: Message is not returned to calling program. 

integer by value (optional) 

When buff is specified, buffsize is the size, in bytes, of the buffer. When 

buff is not specified, buffsize is the length, in bytes, of the records 

written to the destination file. 

Default: 72 bytes. 

logical by value (optional) 

A 16-bit logical mask indicating parameter types for parml, parm2, 

parm3, parm4, and parm5. The bit settings are as follows: 

2=123 



GENMESSAGE 



parml 



parm2 



parm3 



parm4 



parm5 



msgdest 



Bit (0:1) = 1. Ignore rest of word and parameters parml through parm5. 

=0. Rest of word, in 3-bit groupings, will specify parameter 
types for parml, parm2, parm3, parm4, and parmS, as 
follows : 

Bits (1:3)= parml type. 

- parameter is a string, terminated by an ASCII null (0). 

1 - parameter is integer. 

2 - parameter is double by reference. 

3 - ignore the parameter. 

Bits (4:3) = parm2 type (types same as for parml). 
Bits (7:3) = parm3 type (types same as ioxparml). 
Bits (10: 3) =parm4 type (types same as for parml). 
Bits (13:3)= parm5 type (types same as for parml). 
Default: Parameters parml through parm5 will be ignored. 

logical by value (optional) 

Parameter to be inserted into message. If parmask specifies a type of 
(string), parml must pass the byte address (i.e., @stringarray) of the 
byte array containing the string. If parmask specifies type 2 (double by 
reference), parml must pass the word address (i.e., @doublename) of 
the doubleword identifier containing the value. 

logical by value (optional) 

Parameter to be inserted into message. Description is the same as for 

parml. 

logical by value (optional) 

Parameter to be inserted into message. Description is the same as for 

parml. 

logical by value (optional) 

Parameter to be inserted into message. Description is the same as for 

parml. 

logical by value (optional) 

Parameter to be inserted into message. Description is the same as for 

parml. 

integer by value (optional) 

Integer value specifying the destination of the assembled message, as 

follows : 

= $STDLIST. 

>2 = File number of destination file. 

Default: $STDLIST if buff is not specified, no file if buff is specified. 
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GENMESSAGE 



errnum integer (optional) 

Integer identifier to which an error number is returned. Values returned 
are as follows : 

= Successful execution. 

1 = FREADLABEL failed on catalog file. 

2 = FREAD failed on catalog file. 

3 = Specified setnum not found in catalog. 

4 = Specified msgnum not found in catalog. 

6 = Assembled message overflowed buffer (if msgdest was specified, 

however, message routed correctly). 

7 = write failed to destination file. 

8 = Catalog file opened with improper access options. 

11 = filenum parameter not specified. 

12 = setnum parameter not specified. 

13 = msgnum parameter not specified. 

14 = setnum <= 0. 

15 = setnum > 62. 

16 = msgnum <= 0. 

17 = buffsize <= 0. 

18 = msgdest < 0. 

CONDITION CODES 

CCE Successful execution. 

CCL Intrinsic did not execute because of file system error. 

CCG Intrinsic did not execute. May have missing required parameter, invalid 



i**i _ j-**-\*~s 



parameter, or invalid me numDer oi catalog or destination me. ^ou is 
also returned if SET or MSG is not found. 



TEXT DISCUSSION 

Page 4-50 
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GET 

Receives the next request from the remote master program. 

I J A 1 

ifun:<*GET{itag,iVonumber); 
See the DS/3000 Reference Manual (32190-90001) for a discussion of this intrinsic. 
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GETDSEG 



Creates an extra data segment. INTRINSIC NUMBER 150 



■I:; ■ L ILV 

GETDSEGiinde.x.kngtk.id); 

The GETDSEG intrinsic creates or acquires an extra data segment. The number of extra data 
segments that can be requested, and the maximum size allowed these segments, are limited by 
parameters specified when the system is configured. When an extra data segment is created, the 
GETDSEG intrinsic returns a logical index number to the calling process. This index number is 
assigned by MPE and allows this process to reference the segment in later intrinsic calls. The 
GETDSEG intrinsic also is used to assign the segment the identity that either allows other processes 
in the job or session to share the segment, or that declares it private to the calling process. If the 
segment is sharable, other processes can obtain its logical index (through GETDSEG) and use this 
index to reference the segment. Thus, the logical index is a local name that identifies the segment 
throughout any process that obtained the index with the GETDSEG call. The logical index need not 
be the same value in all processes sharing the data segment. The identity, on the other hand, is a 
job-wide or session-wide name that permits any process to determine the logical index of the 
segment. If the intrinsic is called in user mode, then the data segment is initially filled with zeros. 

PARAMETERS 

index logical (required) 

A word to which the logical index of the data segment, assigned by 
MPE, is returned. 

length integer (required) 

The maximum size of the data segment requested, if the segment is not 
yet created, or the word to which the maximum size of the segment is 
returned, if the segment already exists. 

id logical by value (required) 

A word containing the identity that declares the data segment sharable 
between other processes in the job/session, or private to the calling 
process. For a sharable segment, id is specified as a non-zero value. If a 
data segment with the same id exists already, it is made available to the 
calling process. Otherwise, a new data segment, sharable within the 
job/session, is created with this id. For a private data segment, an id of 
zero must be specified. 

CONDITION CODES 

CCE Request granted. A new segment was created. 

CCG Request granted. An extra data segment with this identity exists 

already. 
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GETDSEG 



CCL Request denied. An illegal length was specified (index is set to %2000), 

or the process requested more than the maximum allowable number of 
data segments (index is set to %2001), sufficient storage was not 
available for the data segment (index is set to %2002) or a stack 
expansion necessary to satisfy the request could not be done because 
the stack was frozen (index set to %2003). Note that a stack expansion 
is usually not necessary to get an extra data segment. 

SPECIAL CONSIDERATIONS 

Data Segment Management Capability required. 

TEXT DISCUSSION 

Page 8-6. 
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GETJCW 

Fetches content of system job control word (JCW). INTRINSIC NUMBER 73 

L %kl:W»«2 

jcu/:=GETJCW; 

The GETJCW intrinsic returns the complete job control word (JCW) to the calling process. 

FUNCTIONAL RETURN 

This intrinsic returns the job control word. This word is structured for a desired purpose by the 
calling program through the SETJCW intrinsic or PUT JCW intrinsic. 

CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 

Page 4-46 
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GETLOCRIN 



INTRINSIC NUMBER 30 Acquires local RIN's. The number acquired = rincount. 



LV 
GETLOCRIN(ri/jf ount ); 



Just as global Resource Identification Numbers (RIN's) must be acquired by users before they can 
be used in jobs/sessions, local RIN's must be acquired by a job/session before they can be used 
within the job/session. This is done by using the GETLOCRIN intrinsic. 

PARAMETERS 

rincount logical by value (required) 

The number of local RIN's to be acquired by the job/session. The 
maximum number of RIN's available is defined when the system is 
configured. 

CONDiTiON CODES 

CCE Request granted. 

CCG Request denied. RIN's already are allocated to this job. Additional 

RIN's cannot be allocated until these RIN's are released. 

CCL Request denied. Not enough RIN's are available to satisfy this call. 

None are allocated to this job. 

TEXT DISCUSSION 

Page 6-8. 
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Determines source of activation call. INTRINSIC NUMBER 105 

I 

After a suspended process is reactivated, it can determine whether the source of the activation 
request was its father process, one of its son processes, or whether the reactivation was by an 
interrupt or the timer. 

FUNCTIONAL RETURN 

This intrinsic returns one of the following codes: 

1 = Activated by father. 

2 = Activated by a son. 

= Activated from some other source. 

CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

Process Handling Capability required. 

TEXT DISCUSSION 

Page 7-14. 
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GETPRIORITY 



INTRINSIC NUMBER 120 



Reschedules a process. 



IV 
GETPRIORITY^m, 



hV IV fKV 



When a process is created, it is scheduled on the basis of a priority class assigned by its father. After 
this point, the priority class of the created process can be changed at any time by using the 
GETPRIORITY intrinsic. 

NOTE 

A process can change its own priority or that of its son but it 
cannot reschedule its father. 

The GETPRIORITY intrinsic will abort the calling process if the requested priority class exceeds the 
maximum allowable priorityclass of the rescheduled process or specifies an invalid priority class. 



PARAMETERS 



pin 



priorityclass 



integer by value(required) 

An integer specifying the process whose priority is to be changed. If 
this is a son process, the integer is the process Process Identification 
Number (PIN). If this is the calling process, the integer is zero. 

logical by value(required) 

A 16-bit word that contains two ASCII characters describing the priority 
class in which the process is rescheduled. This may be "AS", "BS", 
"CS", "DS", or "ES". For users running in Privileged Mode, the prior- 
ityclass parameter may be specified as an absolute number by x A, 
where x is an 8-bit priority number and A is the ASCII character "A". 
For example, a request for a priorityclass of 31 in the master queue 
would be requested as %017501. Note that an absolute priority must be 
specified in order to overcome the MAXPRI setting of an account. 



NOTE 



rank 
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Scheduling a process into the "AS" or "BS" priority class 
(assuming the process's maximum priority allows such a specifi- 
cation) can result in the rescheduled process deadlocking the 
system or locking out system and user processes from execu- 
tion. 

integer by value( optional) 

This parameter is used only for compatibility with previous versions of 

the MPE Operating System. It is ignored for all users. 



GETPRIORITY 



CONDITION CODES 

CCE Request granted. 

qqq Request denied because the process specified is not alive. 

CCL Request denied because an illegal PIN was specified. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

Process Handling Capability required. 

Must be running in Privileged Mode to specify absolute priority. 

TEXT DISCUSSION 

Page 7-13. 
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GETPRIVMODE 



INTRINSIC NUMBER 200 Dynamically enters privileged mode. 

GETPRIVMODE. O-P 

The GETPRIVMODE intrinsic switches a temporarily -privileged program from the non-privileged 
mode to the privileged mode. This intrinsic turns the privileged mode bit in the status register on, 
but leaves the privileged mode bit in the Code Segment Table (CST) entry for the executing 
segment unchanged. The status register, rather than the CST, determines a mode change when 
running in privileged mode. Thus, if additional segments are to be run as part of the program, they 
will be run in privileged mode unless an intrinsic is called specifically to return to the non-privileged 
mode. 

The calling process is aborted if the program file does not possess the Privileged Mode Capability, 
and the CST indicates non-privileged mode. 

CONDITION CODES 

CCE Request granted. The program, was in non-privileged mode when the 

intrinsic call was issued. 

CCG Request granted. The program was already in privileged mode when the 

intrinsic call was issued. 

CCL Not returned by this intrinsic. 

SPECIAL CONSIDERATIONS 

Privileged Mode Capability required. 

TEXT DISCUSSION 

Page 9-3. 

IMPORTANT NOTE 

The normal checks and limitations that apply to the standard 
users in MPE are bypassed in privileged mode. It is possible 
for a privileged mode program to destroy file integrity, includ- 
ing the MPE operating system software itself. Hewlett-Packard 
will investigate and attempt to resolve problems resulting 
from the use of privileged mode code. This service, which is 
not provided under the standard Service Contract, is available 
on a time and materials billing basis. However, Hewlett- 
Packard will not support, correct, or attend to any modifica- 
tion of the MPE operating system software. 
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GETPROCID 

_ , „~ T » „.„„„« TlVrTRTOSTP 1NITTMRET? 112 

Kequests fih 01 a son process. ^\ ^v^n-^ ^ „.v...di„. - — 

I IV 

A process can. determine the Process Identification Number (PIN) assigned to any of its sons by 
using the GETPROCID intrinsic. 

FUNCTIONAL RETURN 

This intrinsic returns the PIN of the specified son process. 

PARAMETERS 

numson integer by value (required) 

A number from 1 to n which specifies the chronological son's PIN 
desired. The value n cannot exceed the number of sons in existence. 
For example, a father process has three sons and it is desired to know 

tile TUN UI tllC OCV/U11U DUlli Hit. VOIUV/ ^J. nwriiOvit wvn ,.ww.*« ~~ — . 

If n exceeds the number of sons currently attached to this calling 
process, a zero is returned. If n is less than 1, the PIN of the first son 
(or zero if no sons exist) is returned. 

CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

Process Handling Capability required. 

TEXT DISCUSSION 

Page 7-15. 
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INTRINSIC NUMBER 110 Requests status information about a father or son process. 



D TV 

statinfo :=GETPROCINFO(pw); 



Information about a father or son process can be obtained with the GETPROCINFO intrinsic. 

FUNCTIONAL RETURN 

This intrinsic returns a double-word message denoting the following information about a father or 
son process: 

Word 1: 

Bits (8:8) — The process' priority number in the master queue. 

Bits (0:8) — Reserved for MPE. These bits are set to zero by the system. 

Word 2: 

Bit (15:1) — Activity state. 

1 = The process is active. 

= The process is suspended. 
Bit (13:2) — Suspension condition. Set only if bit 15 = 0. 

If bit 14 = 1, the source of the expected activation is the father. 

If bit 13 = 1, the source of the expected activation is a son. 
Bits (9:4) — Reserved for MPE. These bits are set to zero by the system. 
Bits (7:2) — Origin of the last ACTIVATE intrinsic call. 

00 = The process was activated by MPE. 

01 = The process was activated by the father. 
10 = The process was activated by a son. 

Bits (4:3) — Queue Characteristics. 

001 = DS or ES priority class. 

010 = CS priority class. 

100 = Linearly scheduled (AS or BS or Master queue). 
Bits (0:4) — Reserved for MPE. These bits are set to zero by the system. 

PARAMETERS 

pin integer by value (required) 

The process to which the returned message pertains. If this is a request 
for a father process, pin must be zero. If it is a request for a son 
process, pin is the PIN of that process. 

CONDITION CODES 

CCE Request granted. 

CCG Request denied because the process is being terminated. 

CCL Request denied because an illegal PIN was specified. 



2-136 



GETPROCINFO 



SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

Process Handling Capability required. 

TEXT DISCUSSION 

Page 7-15. 
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INTRINSIC NUMBER 201 Dynamically returns to non-privileged mode. 

GETUSERMODE; 

The GETUSERMODE intrinsic changes a temporarily-privileged program from the privileged to the 
non-privileged mode. 

This intrinsic changes the privileged mode bit in the status register to off, and is the complement of 
the GETPRIVMODE intrinsic. 

CONDITION CODES 

CCE Request granted. The process was in privileged mode when the intrinsic 

call was issued. 

CCG Request granted. The program was in non-privileged mode when the 

intrinsic call was issued. 

CCL Not returned by this intrinsic. 

SPECIAL CONSIDERATIONS 

Privileged Mode Capability required. 

TEXT DISCUSSION 

Page 9-5. 
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INITUSLF 



Initializes buffer for a USL file to the empty state. 



INTRINSIC NUMBER 82 



I IV IA 

errnum:=imrUSLF{us!fnuin,recQ)i 



The INITUSLF intrinsic initializes the first record (record 0) of a USL file to the empty state. 

FUNCTIONAL RETURN 

This intrinsic returns an error number if an error occurs. If no error occurs, no value is returned. 



PARAMETERS 

uslfnum 



recO 



integer by value (required) 

A word identifier supplying the file number of the USL file. 

integer array (required) 

A 128-word buffer, corresponding to the first record of the USL file 
(record 0), to be initialized to the empty state. This buffer should be 
set to all zeros. The intrinsic will set certain values in record before 
returning to the calling program. See the MPE Segmenter Reference 
Manual for record format. 



CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied. One of the error numbers listed below is returned 

Error Number Meaning 





An unexpected end-of-file was encountered 
when writing to uslfnum. 

Unexpected input/output error occurred. 



TEXT DISCUSSION 

See the MPE Segmenter Reference Manual 
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IODONTWAIT 



INTRINSIC NUMBER 22 



Initiates completion operations for an I/O request. 



I IV l,A I I. O-V. 

; hum -)Ol h'Wm MJiJiienum, large tjc nunt,cstation) , 



The IODONTWAIT intrinsic behaves the same as IOWAIT (see page 2-128) with one exception: 

If IOWAIT is called and no I/O has completed, then the calling process is suspended until some 
I/O completes; if IODONTWAIT is called and no I/O has completed, then control is returned to 
the calling process (CCE is returned and the result of IODONTWAIT is zero.) 



FUNCTIONAL RETURN 

This intrinsic returns an integer representing the file number for which the completion occurred, 
no completion occurred, zero is returned. 



If 



PARAMETERS 

filenum 



target 



integer by value (required) 

A word identifier specifying the file number for which there is a pend- 
ing I/O request. If zero is specified, the IODONTWAIT intrinsic will 
check for any I/O completion. 

logical array (optional) 

A word pointer specifying the DB-relative address of the user's input 
buffer. This buffer must large enough to contain the input record. It 
should be the same buffer specified in the original I/O request if that 
request was a read. This allows for proper recognition of :EOD (AND :) 
where applicable. 



tcount 



integer (optional) 

A word to which is returned a positive integer representing the length of 

the received or transmitted record. If the original request specified a byte 

count, the integer represents bytes; if the request specified words, the 

integer represents words. Note that this parameter is pertinent only if 

the original request was a read. The FREAD intrinsic always returns 

zero as its functional return if no-wait I/O is specified. In this case, the 

actual record length is returned in the tcount parameter of 

IODONTWAIT. 

Default: The length of the record is not returned. 



cstation 



logical (optional) 

Used for distributed systems to return the number of the calling station 

which completed. 
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CONDITION CODES 

rrE Request granted. If the functional return is non-zero then I/O com- 

pletion occurred with no errors. If the return is zero then no I/O has 
completed. 

CCG An end-of-file condition was encountered. 

Request denied. Normal I/O completion did not occur because there 
were no I/O requests pending, a parameter error occurred, or an ab- 
normal I/O completion occurred. 

SPECIAL CONSIDERATIONS 

You must be running in Privileged Mode to specify FOPEN aoptions No-Wait I/O. 



TEXT DISCUSSION 

Page 10-62 



2-141 



IOWAIT 



INTRINSIC NUMBER 22 



Initiates completion operations for an I/O request. 



T IV LA I L OV 

fnUm:=lOWAlT(filenum, target jeount ; cstation); 

If a file has been opened with the no-wait I/O mode aoption of the FOPEN intrinsic (aoptions bit 
(4:1) = 1), all read and write requests must be followed by the IOWAIT intrinsic call. This intrinsic 
initiates completion operations for the associated I/O request, including data transfer into the user's 
buffer area if necessary. 

The IOWAIT intrinsic call must precede any subsequent I/O request against the file. Within this 
restriction, the IOWAIT intrinsic call can be delayed as long as desired to allow effective I/O and 
processing overlap. 

FUNCTIONAL RETURN 

This intrinsic returns an integer representing the file number for which the completion occurred. If 
no completion occurred, zero is returned. 

PARAMETERS 



filenum 



target 



integer by value (optional) 

A word identifier specifying the file number for which there is a 
pending I/O request. If zero is specified, the IOWAIT intrinsic will wait 
for the first I/O completion. 

logical array (optional) 

A word pointer specifying the DB-relative address of the user's input 
buffer. This buffer must be large enough to contain the input record. It 
should be the same buffer specified in the original I/O request if that 
request was a read. This allows for proper recognition of :EOD (and:) 
where applicable. 



tcount 



integer (optional) 

A word to which is returned a positive integer representing the length of 
the received or transmitted record. If the original request specified a byte 
count, the integer represents bytes; if the request specified words, the 
integer represents words. Note that his parameter is pertinent only if the 
original request was a read. The FREAD intrinsic always returns zero as 
its functional return if no-wait I/O is specified. In this case, the actual 
record length is returned in the tcount parameter of IOWAIT. 
Default: The length of the record is not returned. 



cstation 



logical (optional) 

Used for distributed systems to return the number of the calling station 

which completed. 
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CONDITION CODES 

CCE Request granted. I/O completion occurred with no errors. 

QCG An end-of-file condition was encountered. 

CCL Request denied. Normal I/O completion did not occur because there 

were no I/O requests pending, a parameter error occurred, or an 
abnormal I/O completion occurred. 

SPECIAL CONSIDERATIONS 

You must be running in Privileged Mode to specify FOPEN aoptions No-Wait I/O. 

TEXT DISCUSSION 

Page 10-59 
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New Intrinsic JOBINFO 



By Larry Cargnoni 

The JOBINFO intrinsic is new for MPE V/E, and will execute only on an HP 3000 supporting MPE 
V/E It enables a standard user to access session- and job-related information. Previously, most of 
this information was accessible only through MPE commands and the WHO intrinsic. The JOBINFO 
intrinsic is patterned after the FFILEINFO and CREATEPROCESS intrinsics . It is callable from any 
language and may be used in software that performs security checks, job stream polling, system ac- 
counting' and job/session communication. The JOBINFO intrinsic provides access to information re- 
lated to any job/session that is current to the system. This intrinsic is expandable, and is written so 
that the addition of further functionality will be straightforward. 



SYNTAX 



IV D LA IV LA I OV 

JOBI NFOCisind, JSItrmn y stabus I ,itemnvml ,iteml .errornuml ] 

[ ,itemnum2,item2,errornum2~l 
[ ,itemnum$ , itemd , erromvml ] 
t , itemnum4 , item4 s errornvm4 1 
[ ,itemnianS ,itemS ^errornumS ] ) ; 



PARAMETERS 



jsind 



integer by value (required) 

An integer indicating whether the JStinnn is a session or job: 



1= JS§nnn is a session. 
2= JS§nnn is a job. 



JSfnnn 



double (required) 

A double value, 32 bits, identifying the job or session for wmcn mu 

tion will be retrieved . 



status 



logical array (required) 

A" two word logical array reporting the overall success/failure of the call. 

Only the first word contains significant information . 

0= Successful call . All errornums equal zero . 

1= Semi-successful call. One or more errornums were returned with non- 
zero values. 
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itemnum 



item 



errornum 



Intrinsics 

2- Unsuccessful call- All errornums were returned with nonzero values. 

3- Unsuccessful call . Syntax error in calling sequence . 

4» Unsuccessful call . Unable to retrieve JStinnn/Sitnnn . 

5» Process died during the start of retrieval . 

integer by value (optional) 

Cardinal number of the item desired. This specifies which item value is to 

be returned (refer to "ITEM*" in Table 1). 

logical array (optional) 

Name of a reference parameter (whose data type corresponds to the data 
type for the desired information) to which the desired information is 
returned (refer to "ITEM" in Table 1). 

integer (optional) 

A returned integer specifying the success or failure of the retrieval of each 

item. The returned values are: 

0* Successful information retrieval. 

1* Invalid itemnum (item number). 

2- Desired information not pertinent to the given JS#nnn (eg user 
specifies a session number and wishes to know if a job had RESTART 
option) . 

3i User has insufficient capability to access this information. 

4= The desired information is no longer available (eg., when spoolfiles 
disappear). 



SPECIAL CONSIDERATIONS 

A user without System Manager (SM) or Account Manager (AM) capability ca »^ "^J "^ 
tion about the jobs/sessions logged on under the user name and account. A user with AM capabil ty 
but not SM capability will be restricted to information concerning hi. account sessions and jobs , a user 
with SM capability will be able to retrieve imurm^vu „„.„,«„«.. ~. """""I ~" ' r ~\ hrou2 h MPE 
tion to the above security is access to items which are normally available to a user, through Mrt 
commands, who does not have any special capabilities. 



CONDITION CODES 

There are no condition codes in the traditional sense, but the status parameter can be thought oi 
condition code . 
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The status parameter returns a number representing the overall status of the call. The errornum pa- 
rameter returns the status of the individual accesses items and itemnums . Combinations of successful 
and unsuccessful data retrievals could be returned from the same call. For example., a user who does 
not have System Manager or Account Manager capabilities writes a program with JOBINFD . The 
JDBINFO intrinsic retrieves the jobfence and the current job step of access user. Upon the return of 
JOBINFD , the parameter status will return a 2 (semi-successful call). The call is not successful since 
the errornum corresponding to the jobfence access will be (successful retrieval) and the errornum 
corresponding to the current job step access will be a 3 (insufficient capability). 

Table 1 . Item Descriptions 



LA 
LA 



ITEM# ITEM (information returned) DATA TYPE 

1 [JSNAMEJuser. account (See note 1) LA 

2 session/job name (See note 2) LA 

3 user name (See note 2) LA 

4 user logon group (See note 2) LA 

5 user account (See note 2) LA 

6 user home group (See note 2) LA 

7 session/job introduction time (See note 3) LA 

8 session/job introduction date (See note 4) 

9 input ldev/class name (See note 2) 

10 output ldev/class name (See note 2) LA 

11 current job step (See note 5) LA 

12 current number of jobs I 

13 current number of sessions I 

14 job input priority 1 

15 job/session number D 

16 jobfence * 

17 job output priority I 

18 number of copies ^ 

19 job limit (system) 1 

20 session limit (system) * 

21 job deferred (See note 6) I 

22 main PIN - CI PIN for job/session L 

23 original job-spooled (See note 6) L 

24 RESTART option (See note 6) L 

25 sequenced - job (See note 6) L 

26 term code (See note 7) L 

27 CPU limit L 

28 session/job state (See note 8) L 

29 user's local attributes D 

30 SSTDIN spoolfile number (See notes 9 4 10) I 

31 SSTDIN spoolfile status (See notes 9 & ii) I 

32 SSTDLIST spoolfile number (See notes 9 4 10) I 

33 SSTDLIST spoolfile status (See notes 9 & 11) I 

34 length of current job step of item number 11 I 

35 -.SET $STDLIST;DELETE invoked (See note 12) L 

36 Job Information Table data segment number L 
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Table 1 (continued). Item Number Notes 



1. 


A maximum of 26 charact 


ers are allowed for input. Input must be in the 




form [jsname , ]user. account . The wild card character (@) is not allowed. 


2. 


A maximum of 8 characl 


ers are returned. 


3. 


Returns a 32-bit dou 
int rinsic . 


bl 


e word in a form to be used by the FMTCLOCK 


4. 


Returns a 16-bit logics 


1 word in a form to be used by the FMTCALENDAR 




intrinsic. 






5. 


Returns a maximum of 


283 characters , and is the image of the command 




currently executing. 






6. 


Returns the values: 


M 


No. 




1 


M 


Yes. 


7. 


Returns the values: 


m 


Regular terminal. 




1 


X 


Regular terminal with special log on. 




2 


* 


APL terminal. 




3 


' 


nrl i e i 1114 noi. 


8. 


Returns the values: 2 


■ 


Executing . 




4 


c 


Suspending. 




32 


s 


Wait. 




48 


at 


Initialization . 


9. 


Returns data for current jobs and sessions. SSTDIN/SSTDLIST files only. 


10. 


Returns the spoolfile 


number as an integer. 


11. 


Returns the values: 


■ 


Active . 




1 


s 


Ready. 




2 


■ 


Open . 




3 


= 


Locked . 




Da4 nrnf 4ke ifll iiae • A 


■ 


CCTDI TCT will ha eauari 




1 


m 


:SET SSTDLIST=D£LETE is invoked. 



All •is>w>»w.»v7. nnA i*A»v» n-srimatsrc orp /vntmit noramptprc u/it*h rmp PYrpntinn Ttf*m nnmhfr 1 can he 

used for an input and output parameter. Item number 1 is an input parameter only if the user is 
retrieving data by the Parse Method of Retrieval (Refer to the MPE V Intrinsics Reference Manual 
(32033-90007)). Otherwise, it is an output parameter. The number of characters returned is 
twenty -six or less. The returned message will be left justified and padded with blanks: 

[jsname, luser .account 

A useful program would be to poll a user's : STREAM job to determine what job step it is currently ex- 
ecuting . The following piece of pseudo code could be used to accomplish this : 
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INTRINSIC NUMBER 102 Deletes a process. 

iv 

KILL</rfw); 
A process can delete one of its sons by using the KILL intrinsic. 

PARAMETERS 

pin integer by value (required) 

A word containing the Process Identification Number (PIN) of the 
process to be deleted. The value of pin must be an integer ranging from 
1 to 255. 

CONDITION CODES 

CCE Request granted. 

CCG Request granted. The specified process was terminating. 

CCL Request denied because an illegal PIN was specified. 

SPECIAL CONSIDERATIONS 

Process Handling Capability required. 

TEXT DISCUSSION 

Page 7-8. 
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Dynamically loads a library procedure. INTRINSIC NUMBER 80 



I BA IV J 

idcni iwm -~LO ADPROCiproaiatHcJib.plabel) ; 



The LOADPROC intrinsic dynamically loads a library procedure, together with external procedures 
referenced by it. 

FUNCTIONAL RETURN 

This intrinsic returns an identity number required for use in unloading the procedure. If an error 
occurs, an error code number is returned instead of the identity number. 

PARAMETERS 

procname byte array (required) 

Contains the name of the procedure to be loaded. The name must be 
terminated by a blank. 

lib integer by value (required) 

An integer value of 0, 1, or 2, to request library searching for the 
procedure, as follows: 

= Search the system library only. 

1 = Search libraries in this order: 

Account public library. 
System library. 

2 = Search libraries in this order: 

Group library. 
Account public library. 
System library. 

plabel integer (required) 

The word to which the procedure's label (P-label) is returned. This is 
the external P-Iabei so that the SPL construct ASSEMBLE (PCAL 0) 
may be used. 

CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied. The value returned to the calling process is a loader 

error code. See Section X for a description of error codes. 

TEXT DISCUSSION 

Page 4-2. 
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INTRINSIC NUMBER 34 



Locks a global RIN. 



LOCKGLOR1 N(nmmm, 






Any global Resource Identification Number (RIN) assigned to a group of users can be locked, by 
one process at a time, by using the LOCKGLORIN intrinsic. When this is done, any other processes 
that attempt to lock this RIN are suspended. 

To use the LOCKGLORIN intrinsic, you must know both the RIN number and the RIN password. 
Users with only Standard MPE Capability cannot lock more than one global RIN simultaneously. 
An attempt by such a user to lock more than one RIN simultaneously aborts the process. 



PARAMETERS 



nnnum 



integer by value (required) 

A word identifier specifying the RIN number of the resource to be 
locked. This is the RIN number furnished in the :GETRIN command. 
See the MPE Commands Reference Manual for a description of the 
:GETRIN command. 



lockcond 



tinpassword 



logical (required) 

A word identifier specifying conditional or unconditional RIN locking, 

as follows: 

TRUE = Locking will take place unconditionally. If the RIN is not 
available, the calling process suspends until it becomes 
available. The TRUE condition is passed as a word in which 
bit 15 is 1. All other bits are ignored. 

FALSE = Locking takes place only if the RIN is immediately available. 
If the RIN is not immediately available, control returns to 
the calling process immediately with the condition code 
CCG. The FALSE condition is passed as a word in which bit 
15 is 0. All other bits are ignored. 

byte array (required) 

Contains the RIN password assigned through the :GETRIN command. 

This array must be a minimum of 10 bytes in length and must be 

terminated by a non-alphanumeric ASCII character (a blank is 

recommended). 



CONDITION CODES 

The condition codes possible if lockcond = TRUE are 



CCE 



Request granted. If the calling process had already locked the RIN, 
FALSE is returned to the word lockcond. If the RIN was free, TRUE 
is returned to lockcond. 



CCG 



Not returned. 
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CCL Request denied because of invalid RIN. Rinnum is not a global RIN or 

the value is out of bounds for the RIN table. 

The condition codes possible if lockcond = FALSE are 

CCE Request granted. If the calling process had already locked the RIN, 

FALSE is returned to the word lockcond. If the RIN was free, TRUE is 
returned to lockcond. 

CC G Request denied because the RIN was locked by another job. 

CCL Request denied because of invalid RIN. Rinnum is not a global RIN or 

the value is out of bounds for the RIN table. 

SPECIAL CONSIDERATIONS 

Multiple RIN Capability is required if you are going to lock more than one global RIN at a time 
within a process. 

TEXT DISCUSSION 

Page 6-3. 
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INTRINSIC NUMBER 32 Locks a local RIN. 



IV 



Any local Resource Identification Number (RIN) assigned to a job can be locked, by one process at 
a time, by using the LOCKLOCRIN intrinsic. When this is done, other processes within the job that 
attempt to lock that RIN are suspended until the locked RIN is released. 

PARAMETERS 

rinnum integer by value (required) 

An identifier specifying one of the previously-allocated local RIN's, 
designated by an integer from 1 to the value specified in the rincount 
parameter of the GETLOCRIN intrinsic. 

lockcond logical (required) 

A word identifier specifying conditional or unconditional locking, as 

follows: 

TRUE = Locking takes place unconditionally. If the RIN is not 
available, the calling process suspends until the RIN becomes 
available. The TRUE condition is passed as a word in which 
bit 15 is 1. All other bits are ignored. 

FALSE = Locking takes place only if the RIN is immediately available. 
If it is not, control returns to the calling process immediately 
with the condition code CCG. The FALSE condition is 
passed as a word in which bit 15 is 0. All other bits are 
ignored. 

CONDITION CODES 

The condition codes possible if lockcond = TRUE are 

CCE Request granted. If the calling process had already locked the RIN, 

TRUE is returned to the word lockcond. If the RIN was free, FALSE is 
returned to lockcond. 

CCG Not returned. 

CCL Request denied because the RIN was invalid. Possibly due to: rinnum 

too large, no local RIN allocated, or rinnum specified a number less 
than or equal to zero. 

The condition codes possible if lockcond = FALSE are 

CCE Request granted. If the calling process had already locked the RIN, 

TRUE is returned to the word lockcond. If the RIN was free, FALSE is 
returned to lockcond. 
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CCG Request denied because the RIN was locked by another process. 

CCL Request denied because the RIN was invalid. Possibly due to: rinnum 

too large, no local RIN allocated, or rinnum specified a number less 
than or equal to zero. 

TEXT DISCUSSION 

Page 6-8. 
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LOG STATUS 



INTRINSIC NUMBER 214 



Provides information about an opened user logging file. 



D LA I 
!,(>( ;SJ'ATl \S ( index. famnlo.tiatiiH i 



The LOGSTATUS intrinsic is used to obtain information about the opened logging file. Its primary 
use is to determine the amount of space used and remaining in a disc logging file. 



PARAMETERS 



index 



loginfo 



double (required) 

The parameter returned from OPENLOG that identifies your access to 

the logging system. 

logical (required) 

A formatted array in which the following information is returned: 



words and 1 
words 2 and 3 
words 4 and 5 
word 6 



total records written in log file 

the size of the logging file 

the space remaining in the log file 

the number of users using the log system 



status 



integer (required) 

An integer in which error information is returned to the caller. Zero 

indicates OK status. 



CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 

None. 
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INTRINSIC NUMBER 36 Determines PIN of process that has locked a local RIN. 

I IV- 

p*«:~U)CRINaWNE« (fltomww); 

After local RIN's have been acquired by a process, they can be locked and unlocked by other 
processes in the process structure. LOCRINOWNER determines the PIN (Process Identification 
Number) of the process that has a particular RIN locked. 

FUNCTIONAL RETURN 

If the particular RIN is locked by the father process of the process which called LOCRINOWNER, a 
is returned. Otherwise, the PIN of the son or brother process which has the local RIN locked' is 
returned. 

PARAMETERS 

rinnum integer by value (required) 

The number of the local RIN (from 1 to the value specified in the 
rincount parameter of the GETLOCRIN intrinsic) for which the PIN of 
the locking process is to be determined. 

CONDITION CODES 

CCE Request granted. 

CCG Request denied. The local RIN specified by rinnum is not currently 

locked by any process. 

CCL Request denied. The rinnum parameter was invalid (was < = 0, greater 

than the RIN table size, or was greater than the number of local RIN's 
currently allocated to this process structure). 



TEXT DISCUSSION 

Page 6-9 
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Tests mailbox status. 



INTRINSIC NUMBER 106 



L IV I 

to fs:=M MUphi.cou U \ 



A process can determine the status of the mailbox used by its father or son with the MAIL intrinsic. 
If the mailbox contains mail that is awaiting collection by this process, the length of this message 
(in words) is returned to the calling process in the count parameter. This enables the calling process 
to initialize its stack in preparation for receipt of the message. 



FUNCTIONAL RETURN 

This intrinsic returns the status of the mailbox, as follows: 



Status Returned 



Meaning 



KAHMivit: i cno 

pin 



count 



The mailbox is empty. 

The mailbox contains previous outgoing mail from 
this calling process that has not yet been collected by 
the destination process. 

The mailbox contains incoming mail awaiting collec- 
tion by this calling process. The length of the mail is 
returned in count. 

An error occurred because an invalid pin was speci- 
fied or a bounds check failed. 

The mailbox is temporarily inaccessible because other 
intrinsics are using it in the preparation or analysis of 
mail. 



integer by value (required) 

An integer specifying the mailbox tested. If this integer specifies the 
mailbox of a son process, it must be the Process Identification Number 
(PIN) of that son. Zero specifies the mailbox of a father process. 

integer (required) 

A word to which an integer denoting the length, in words, of any 

incoming mail in the mailbox is to be returned. 



CONDITION CODES 

CCE Request granted. The mailbox status was tested. 
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CCG Request denied because an illegal pin parameter was specified. The 

value of 3 is returned to the calling process. 

CCL Not returned by this intrinsic. 

SPECIAL CONSIDERATIONS 

Process Handling Capability required. 

TEXT DISCUSSION 

Page 7-10. 
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MYCOMMAND 



Parses (delineates and defines parameters) 
user-supplied command image. 



INTRINSIC NUMBER 71 



j B4 BA IV I »A m BP V-* 

entryno=mmmiAKT>icomimage.delimiters,maxpartm.mMparms,pM 

Within your program, you can extract and format for execution the parameters of a command (that 
is not an MPE command) by using the MYCOMMAND intrinsic. This intrinsic also allows you, at 
your option, to request the searching of a byte array, serving as a command dictionary, for a 
specified command. 

The MYCOMMAND intrinsic aborts the calling process if the number of characters in comimage 
exceeds 255 characters and no delimiter is present. 

FUNCTIONAL RETURN 

If the diet parameter is specified in the intrinsic call, the command entry number is returned. 



PARAMETERS 



comimage 



delimiters 



maxparms 



numparms 



byte array (required) 
Contains either: 

• A command name (expected if the diet parameter is specified), 
followed by parameters, followed by a carriage-return character. 
The command name is delimited by the first non-alphanumeric 
character, and cannot be preceded by any leading blanks. The 
parameters are formatted and referenced in parms array. Also, 
comimage is converted to upper case and the byte array specified 
by diet is searched for a name matching the command. 

• Only command parameters (expected if the diet parameter is not 
specified), followed by a carriage-return character. These para- 
meters will be formatted. Leading and trailing blanks are ignored. 
Lower case is upshifted. 

In the byte array named for the comimage parameter, the first 
character of the parameter list may be a leading blank. 

byte array (optional) 

A byte array containing a string of up to 32 legal delimiters, each of 
which is an ASCII special character. The last character must be a 
carriage return. Each delimiter is identified later by its position in 
this string. 

Default: If this parameter is omitted, the delimiter array "comma, 
equal, semicolon, carriage return" is used. 

integer by value (required) 

An integer specifying the maximum number of parameters expected in 

comimage. 

integer (required) 

A word to which is returned the actual number of parameters found in 

comimage. 
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parms double array (required) 

A double array of maxparms double words that, on return, delineates 
the parameters. When the intrinsic is executed, the first numparms 
double words are returned to the user's process in this array, with the 
first double word corresponding to the first parameter, the second 
double word corresponding to the next parameter, and so forth. The 
parameter fields of comimage are delimited by the delimiters specified 
in delimiters. In formatting, the byte pointer in the first word of parms 
points to the parameter in comimage. The string in comimage is 
upshifted. The second word of parms contains the delimiter number 
and parameter information. Each double word in the array named by 
parms contains the following information: 

Word 1 — Contains the byte pointer to the first character of the para- 
meter. If the parameter is empty or all blanks, points to the delimiter. 

Word 2 — Contains bits that describe the parameter: 

Bits (11:5) =The delimiter number in delimiters, starting at zero. 

Bit (10:1) = If on, indicates that the parameter contains special 

characters other than those in delimiters. 
Bit (9:1) = If on, indicates that the parameter contains numeric 

characters. 
Bit (8:1) = If on, indicates that the parameter contains alphabetic 

characters. 
Bits (0:8) = The length of the parameter, in bytes. This value is zero if 

the parameter is omitted. 

diet byte array (optional) 

A byte array that will be searched for the command name in comimage. 
The format must be identical to that of the diet parameter in the 
SEARCH intrinsic. Actually, the command, delimited by a blank, is 
extracted from comimage, and the SEARCH intrinsic is called with the 
command name used as the target parameter in SEARCH. If the 
command name is found in diet, its entry number is returned to the 
user's program. If the command is not found, or if the diet parameter is 
not specified, zero is returned. If diet is specified but the command 
name is not found in diet, the parameters specified in comimage are not 
formatted. 
Default: is returned. 

defn byte pointer (optional) 

A word to which is returned the relative address of the definition 

portion of the command entry in diet. 

Default: The corresponding information is not returned. 

CONDITION CODES 

CCE The parameters were formatted, without exception. If diet was 

specified, the command entry number was returned to the user's 
program. 
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CCG More parameters were found in comimage than were allowed by 

maxparms. Only the first maxparms of these parameters were 
formatted in parms and returned to the user. 

CCL The diet parameter was specified, but the command name was not 

located in the array diet. The parameters in comimage were not 
formatted. 

TEXT DISCUSSION 

Page 4-4. 
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OPENLOG 



INTRINSIC NUMBER 210 



Provides access to the logging facility. 



D LA u\ I : • 

OPENLOG (index, hgid, pass, mode, status): 

The OPENLOG intrinsic provides access to the user logging facility. 



PARAMETERS 

index 



logid 



pass 



mode 



status 



double (required) 

A double word returned to you which identifies logging access. The 
index is used to check the validity of subsequent calls to WRITELOG 
and CLOSELOG. 

logical array (required) 

An array of up to eight characters which supplies your logging 
identification. The array contains alphanumeric characters. Arrays of 
less than eight characters must end in a space. 

logical array (required) 

An array in which you assign a password associated with the logging 

identifier by the GETLOG command. 

integer (required) 

An integer which you use to indicate whether or not your process 
should be suspended if your request for service cannot be completed 
immediately. Enter a zero if you want to wait for service; enter a one if 
you do not want to wait. 

integer (required) 

An integer which indicates logging system errors to you. (See table 

10-12, User Logging Error Messages.) 



CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 

Page 10-93 
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Suspends the calling process for a specified number of seconds. 



INTRINSIC NUMBER 45 



R 

P -.. SJ ::■■■■" ■■■■ 

PARAMETERS 

interval 



real (required) 

A positive real value specifying the amount of time, in seconds, that the 
process will pause. The maximum time allowed is approximately 
2,147,484 seconds. 



CONDITION CODES 



CCE 
CCG 
CCL 



Request granted. 

Request denied because of insufficient system table (Timer Request 
List) space. 

Request denied because a negative value was specified for interval or 
the value is too large. 



TEXT DISCUSSION 

Page 4-19. 
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PCHECK 



Returns an integer code specifying the 
completion status of the most recently 
executed DS/3000 program-to-program in- 
trinsic. 



1 IV : 

icode:=PCHECK(dsnum); 



See the DS/3000 Reference Manual (32190-90001) for a discussion of this intrinsic. 
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PCLOSE 



Terminates program-to-program communica- 
tion with a remote slave program. 



IV: 



See the DS/3000 Reference Manual (32190-90001) for a discussion of this intrinsic. 
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PCONTROL 



Exchanges tag fields with a remote slave 
program. 



IV | A 

?CONTROL{dsnum,itag); 



See the DS/3000 Reference Manual (32190-90001) for a discussion of this intrinsic. 
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Initiates program-to-program communication 
with a remote slave program. 

1 .' BA J'"' -^bS;' 1A :; BA / IV 

ml 



lv iv iv rv iv 

flag$,stacksize y dlsize, maxdata, bufsize); 



See the DS/3000 Reference Manual (32190-90001) for a discussion of this intrinsic. 
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Requests a remote slave program to send a 
block of data. 



IV IA IV IA 

itag)', 



See the DS/3000 Reference Manual (32190-90001) for a discussion of this intrinsic. 
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Prints character string on job/session listing device. 



INTRINSIC NUMBER 65 



LA IV 



"\ 



You can write a string of ASCII characters from an array to the job/session listing device by using 
the PRINT intrinsic. This intrinsic is similar to issuing an FWRITE intrinsic call against the file 
SSTDLIST The PRINT intrinsic is limited in its usefulness, however, in that the full capability of 
the file system is not available to a user of this intrinsic. For example, :FILE commands are not 
allowed and certain file intrinsics cannot be used because the filenum parameter, obtained from the 
FOPEN intrinsic, is not available to normal users of the PRINT intrinsic. 



PARAMETERS 

message 



length 



control 



logical array (required) 

Contains the character string to be output. 

NOTE 

SPL programmers can avoid annoying warning messages in 
the compiled output by equivalencing a byte array to a 
logical array for the message parameter. 

integer by value (required) 

An integer denoting the length of the character string to be transmitted. 
If length is positive, it specifies the length in words; if length is negative, 
it specifies the length in bytes. Note that if length exceeds the 
configured record length of the device, successive records will be 
written only on terminals. 

integer by value (required) 

An integer representing a carriage-control code as shown in figure 2-3. 



CONDITION CODES 

CCE Request granted. 

QC.G End-of-data was encountered 

CCL 



Request denied because of input/output error. Further error analysis 
through the FCHECK intrinsic is not possible. 



TEXT DISCUSSION 

Page 4-16. 
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INTRINSIC NUMBER 21 Prints a file information display on the job/session list device. 



PRINTFILEINFOtfnwro); 



From SPL (only), a secondary entry point is provided that allows the PRINTFILEINFO intrinsic to 
be called in the following format: 



IV 
PRINTFILElNFOtfm/m) ; 



The PRINTFILEINFO intrinsic causes MPE to print a file information display on the standard list 
device in one of two formats (See Section X). 

■ f\ ^i F\ Rfi **« i Ciiw 

fnum integer by value (required) 

A word containing the file number. 

CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 

Page 10-45 
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Prints a character string on the Operator's Console. INTRINSIC NUMBER 66 



LA IV IV 

?RmTO?{m€ssageJcrigrk,contro!y, 

The PRINTOP intrinsic transmits a string of ASCII characters from an array in your program to the 
Operator's Console. 

PARAMETERS 

message logical array (required) r w acte r 

The array from which the character string is output. The character 
string contained in message is limited to 56 characters. 

length integer by value (required) 

An integer denoting the length of the output string to be transmitted. If 
length is positive, it specifies the length in words; if length is negative, it 
specifies the length in bytes. 

control integer by value (required) 

The value or %320. 



CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because of a physical input/output error. Further error 

analysis through the FCHECK intrinsic is not possible. 

TEXT DISCUSSION 

Page 4-18. 
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INTRINSIC NUMBER 67 Prints a character string on the Operator's Console and solicits a reply. 



LA 



IV LA 



I 



The PRINTOPREPLY intrinsic transmits a string of ASCII characters from an array in your 
program to the Operator's Console and solicits a reply. 

FUNCTIONAL RETURN 

This intrinsic returns a positive integer indicating the length of the reply from the console operator. 
This length represents a word count if expectedl is positive or a byte count if expectedl is negative. 

If expectedl is zero, then the PRINTOPREPLY intrinsic behaves like PRINTOP and does not solicit 
a reply. In this case, the value returned by PRINTOPREPLY is zero. 

If an error occurs, the value returned is zero. 

The parameter length may be zero, in which case only the standard message prefix is written on the 
Operator's Console. If both length and expectedl are zero, then a CCL condition code is returned. 



PARAMETERS 

message 

length 



control 



logical array (required) 

The array from which the characters are output to the Operator's 

Console. The character string is limited to 50 characters. 

integer by value (required) 

An integer denoting the length of the output string to be transmitted. If 
length is positive, it specifies the length in words; if length is negative, it 
specifies the length in bytes. This parameter should never specify a 
message length of more than 50 bytes. 

integer by value (required) 

This parameter must be specified but is not used by MPE. 



reply 



logical array (required) 

The array into which the input characters are read from the Operator's 

Console. 



expectedl 



integer by value (required) 

An integer specifying the maximum length of the message to be read 
into the array reply. If expectedl is positive, it signifies a word count; if 
it is negative, it signifies a byte count. This parameter should never 
specify a reply length of more than 31 bytes. 
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CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because a physical input/output error occurred. Further 

error analysis through the FCHECK intrinsic is not possible. 

TEXT DISCUSSION 

Page 4-18. 
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PROCTIME 

INTRINSIC NUMBER 42 Returns a process' accumulated central processor time. 



D 
time :=PROCTIME; 



The PROCTIME intrinsic is used to obtain the amount of CPU time, in milliseconds, that a process 
has accumulated. This is the basis on which CPU time is charged. (See the : REPORT command in 
the MPE Commands Reference Manual. ) 

FUNCTIONAL RETURN 

This intrinsic returns a double integer value which shows the number of milliseconds that the 
process has been running. 

CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 

Page 4-44. 
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i~i_— t i j-~ — Ai~*i <^41a tntMif -Pfor" T\orjpr +iir»GG 

l^-OplKS, W-* <* uidc J.U.C, u.*j/-m.w **^ii* ^—.jjc-. ^a^c- 

which do not contain X-OFF control 
characters. 



INTRINSIC NUMBER 191 



IV 



ill! 



When using terminals with attached tape readers (such as the ASR-33), you can read data 
programmatically from paper tapes not containing the X-OFF control character, or from tapes 
being read through terminals not recognizing this character, by using the PTAPE intrinsic. PTAPE 
deletes the characters as the tape is read through a terminal which does not recognize these 
characters. 

Tape input terminates when a CONTROL Y (¥<=) character is encountered, returning control to you 
at the terminal. 

Prior to calling this intrinsic, you must be sure to position the end-of-file pointer in the disc file 
(filenum2) to the proper position in the file. If you are reading more than one tape, you should 
specify in the FOPEN intrinsic call that opens the disc file, the append-only aoption and a 
variable-length record format, before the first PTAPE call. In addition, you should set the 
end-of-file pointer to zero, if necessary, before issuing the first PTAPE intrinsic call. 

Lines will be folded at 256-character intervals until a carriage-control character indicates the end of 
a line or until the input is terminated by the Y c character. 



PARAMETERS 

filenuml 



filenum2 



integer by value (required) 

A word identifier specifying the file number of the user's terminal. This 

is the value returned by FOPEN when the terminal file was opened. 

integer by value (required) 

A word identifier specifying the file number of the disc file to which 

the data is to be written. 






CCE 
CCG 

CCL 



Request granted. 

Request denied Decause an error ocuurieu wnuc nuung ^ u^ v^*-^" — 
disc file. 

Request denied because the input file specified is not a terminal or does 
not belong to the calling process, or because insufficient resources, such 
as disc space or main memory, are available to satisfy the request. 



SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Page 5-27. 
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PUTJCW 



Puts value of a particular job control word (JCW) in JCW table. 



B.\ 



The PUTJCW intrinsic puts the value of a job control word (JCW) in the JCW table. If an entry of 
the same name already exists in the table, only its value is entered. If no entry exists for this name, 
an entry is created and its value is entered. 



PARAMETERS 



jcwname 



jcwvalue 



status 



byte array (required) 

A byte array containing the name of the JCW. May contain up to 255 

characters, beginning with a letter and ending with a non-alphanumeric 

character such as a blank. "@" causes all executing JCW's to be set to 

jcwvalue. 

logical (required) 

A word identifier containing the value of the JCW. 

integer (required) 

A word identifier used by the system to return a value denoting the 

execution status of the intrinsic, as follows: 



- Successful execution. Value entered in JCW. 

1 - Error, jcwname greater than 255 characters long. 

2 - Error, jcwname does not start with a letter. 

3 - Error, JCW table overflow. No JCW with this name exists in table 

and unable to create new entry. 



CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 

Page 4-47 
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PWRITE 



Sends a block of data to the remote slave 
program. 

IV IA IV iA 



See the DS/3000 Reference Manual (32190-90001) for a discussion of this intrinsic. 
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QUIT 



INTRINSIC NUMBER 76 Aborts a process. 



IV 
QVLTlmtm ■ 



From within any process in a user program structure, you can abort the process by using the QUIT 
intrinsic. The QUIT intrinsic also transmits a Type 2 abort message (see Section X) to the calling 
process' output device, and sets the job/session in an error state. In batch jobs not containing the 
: CONTINUE command (see the MPE Commands Reference Manual), this results in job termination 
when the entire program finishes. 

PARAMETERS 

num integer by value (required) 

Any arbitrary number. When the QUIT intrinsic is executed, num is 
transmitted as part of the resulting abort message, as follows: 

ABORT: PROG.GROUP.ACCT. %SEG. %LOC 
PROGRAM ERROR: PROCESS QUIT. PARAM= num 

CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

Affects the system job control word. 

TEXT DISCUSSION 

Page 4-20 
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INTRINSIC NUMBER 61 
Aborts a process. 



You may abort the entire user-process structure by using the QUITPROG intrinsic. This intrinsic 
destroys all sons of the job/session main process. The job/session main process is set in the error 
state. In batch jobs not containing the CONTINUE command (see the MPE Commands Reference 
Manual), this terminates the job. 

An abort message (see Section X) is transmitted to the job/session list device. 

PARAMETERS 

num integer by value (required) 

Any arbitrary number. When the QUITPROG intrinsic is executed, num 
is output as part of the abort message, as follows: 

ABORT: PROG.GROUP.ACCT. %SEG. %LOC 
PROGRAM ERROR: PROCESS QUIT. PARAM=m/m 

If num =0, PARAM=num is not printed. 

CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

Affects the system job control word. 

TEXT DISCUSSION 

Page 4-22 
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INTRINSIC NUMBER 64 Reads an ASCII string from an input device. 

I LA f W 

lgth:=READ(message.expectedi); 

The READ intrinsic reads a string of ASCII characters from a job/session input device into an array 
in your program. This intrinsic is similar to issuing an FREAD intrinsic call against the file $STDIN. 
The READ intrinsic is limited in its usefulness, however, in that the full capability of the file system 
is not available to a user of this intrinsic. For example, :FILE commands are not allowed and 
certain file intrinsics cannot be used because the filenum parameter, obtained from the FOPEN 
intrinsic, is not available to normal users of the READ intrinsic. 

Basic line editing such as cancellation of lines and backspacing are performed automatically by the 
input/output driver. If the input device is a terminal and it is in full-duplex mode and the echo 
facility is on, or if the terminal is in half -duplex mode, the characters read are printed. 

FUNCTIONAL RETURN 

This intrinsic returns a positive value representing the length of theASCII string which was read. If 
expectedl is positive, this length specifies words; if expectedl is negative, length specifies bytes. 

PARAMETERS 

message logical array (required) 

The array into which the ASCII characters are read. 

expectedl integer by value (required) 

An integer specifying the maximum length of the array message. If 
expectedl is positive, this specifies the length in words; if expectedl is 
negative, this specifies the length in bytes. When the record is read, the 
first expectedl characters are input. If expectedl equals or exceeds the 
size of the physical record, the entire record is transmitted. 

CONDITION CODES 

CCE Request granted. 

CCG A record with a colon in the first column, signalling the end of data, or 

a hardware end-of-file was encountered. 

CCL Request denied because a physical input/output error occurred. Further 

error analysis through the FCHECK intrinsic is not possible. 

TEXT DISCUSSION 

Page 4-16. 
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Reads an ASCII string from an input device. INTRINSIC NUMBER 64 



I LA IV 

lgth-&E.ADX(message, expected!). 

The READX intrinsic reads a string of ASCII characters from a job/session input device into an 
array in your program. This intrinsic is similar to issuing an FREAD intrinsic call against the file 
$STDINX The READX intrinsic is limited in its usefulness, however, in that the full capability of 
the file system is not available to a user of this intrinsic. For example, :FILE commands are not 
allowed and certain file intrinsics cannot be used because the filenum parameter, obtained from the 
FOPEN intrinsic, is not available to normal users of the READX intrinsic. 

Basic line editing such as cancellation of lines and backspacing are performed automatically by the 
input/output driver. If the input device is a terminal and it is in full-duplex mode and the echo 
facility is on, or if the terminal is in half-duplex mode, the characters read are printed. 

FUNCTIONAL RETURN 

This intrinsic returns a positive value representing the length of the ASCII string which was read. If 
expectedl is positive, this length specifies words; if expectedl is negative, length specifies bytes. 

PARAMETERS 

message logical array (required) 

The array into which the ASCII characters are read. 

expectedl integer by value (required) 

An integer specifying the maximum length of the array message. If 
expectedl is positive, this specifies the length in words; if expectedl is 
negative, this specifies the length in bytes. When the record is read, the 
first expedtedl characters are input. If expectedl equals or exceeds the 
size of the physical record, the entire record is transmitted. 

/-t/MkirM-risMd rnncc 

CCE Request granted. 

«_. .-n/->n .x?r\-c<. — ;*, „ i^u -wn.T -.TOR nr -DATA cnmmand was 

encountered. 

CCL Request denied because a physical input/output error occurred. Further 

error analysis through the FCHECK intrinsic is not possible. 

TEXT DISCUSSION 

Page 4-16. 
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RECEIVEMAIL 



INTRINSIC NUMBER 108 



Receives mail from another process. 



LA 



A process collects mail transmitted to it by its father or a son by using the RECEIVEMAIL 
intrinsic. If the mailbox for the receiving process is empty, the action taken depends on the waitflag 
parameter specified in the RECEIVEMAIL intrinsic call. If the mailbox currently is being used by 
other intrinsics, the RECEIVEMAIL waits until the mailbox is free before accessing it. 

FUNCTIONAL RETURN 

This intrinsic returns one of the following mailbox status codes: 



Status Returned 




2 
3 



PARAMETERS 

pin 



location 



waitflag 



Meaning 

The mailbox was empty and the waitflag parameter 
was FALSE. 

No message was collected because the mailbox 
contained outgoing mail from the receiving process. 

The message was collected successfully. 

An error occurred because an invalid pin was speci- 
fied or a bounds check failed. 

The request was denied because waitflag specified 
that the receiving process wait for mail if the mailbox 
is empty, but the other process sharing the mailbox is 
already suspended, waiting for mail. If both processes 
were suspended, neither could activate the other, and 
they may be deadlocked. 



integer by value (required) 

An integer specifying the process sending the mail. If a son process is 
specified, the integer is the Process Identification Number (PIN) of that 
process. If a father process is specified, the integer is zero. 

logical array (required) 

The array (buffer) in the stack where the message is to be written. 

logical by value (required) 

A word specifying the action to be taken if the mailbox is empty: 
TRUE = Wait until incoming mail is ready for collection. (Bit 15 = 1) 
FALSE = Return immediately to the calling process. (Bit 15 = 0) 
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CONDITION CODES 

C CE Request granted. The mail was collected (the value 2 is returned to 

RECEIVEMAIL) or the mail was not collected because the mailbox 
contained outgoing mail from the receiving process. The value 1 is 
returned to RECEIVEMAIL. 

Ccg Request denied because of an illegal pin parameter. The value 3 is 

returned to RECEIVEMAIL. 

CCL Request denied because the bounds check revealed that the location 

parameter did not define a legal stack address (the value 3 is returned to 
RECEIVEMAIL) or because both sending and receiving processes would 
be awaiting incoming mail (deadlock). The value 4 is returned to 
RECEIVEMAIL. 

SPECIAL CONSIDERATIONS 

Process Handling Capability required. 

TEXT DISCUSSION 

Page 7-12. 
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REJECT 



Rejects a request received by the preceding 
GET intrinsic call and returns an optional tag 
field back to a remote master program.. 

IA 
BMMUV(itag)i 



See the DS/3000 Reference Manual (32190-90001) for a discussion of this intrinsic. 
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RESETCONTROL 

Resets terminal to accept CONTROL-Y signal. INTRINSIC NUMBER 55 

RESETCONTROL; 

To reset the terminal so that a CONTROL-Y signal can be accepted, the RESETCONTROL intrinsic 
is used. To take effect, this intrinsic must be called after the trap procedure is entered. 

i^~ l_J B^S l^J EBB ^^v l^fl ^^^ ^^^ •_ m b^l ^^9 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL, Request denied because the trap procedure was not invoked. 

TEXT DISCUSSION 

Page 4-40. 
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RESETDUMP 

INTRINSIC NUMBER 79 Disables the abort stack analysis facility. 

RESETDUMP; 

PARAMETERS 

None 

CONDITION CODES 

CCE Request granted. 

CCG Abort stack analysis facility was disabled prior to the RESETDUMP call 

and remains disabled. 

CCL Not returned by this intrinsic, 

TEXT DISCUSSION 

MPE DEBUG/Stack Dump Reference Manual. 
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SEARCH 

Searches an array for a specified entry or name. INTRINSIC NUMBER 70 

, BA IV BA BP 0-V 

entryno-SEARCmarget,lertgth.4ict.defn); 

The SEARCH intrinsic searches a specially-formatted array, consisting of sequential entries for a 
specified name. A simple linear search is performed, with the specified name compared against each 
erTtry of the specially-formatted array. Because the search is linear, the most frequently used name 
byte arrays should appear at the beginning of the array to insure efficient searching. 

FUNCTIONAL RETURN 

This instrinsic searches diet for a word matching target, and returns the corresponding entry number 
to the user's program. If the name specified in target is not found, a zero is returned. 

PARAMETERS 

target b y te arra y (required) 

Contains the name for which the search is to be performed. 

length integer by value (required) 

An integer specifying the length, in bytes, of the byte array target 

dl ct byte array (required) 

The specially-formatted array which is to be searched for target. 

defn byte pointer (optional) 

A word to which is returned the address of the definition portion of the 

entry sought in the array. 

Default: If defn is omitted, the address is not returned. 

CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 

TJo^Q A. 9. 
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INTRINSIC NUMBER 107 



Sends mail to another process. 



IV IV LA 

=SENDblAlUpin,couMjocatlon, 



\ 



A process sends mail to its father or sons by using the SENDMAIL intrinsic. If the mailbox for the 
receiving process contains a message sent previously by the calling process but not collected by the 
receiving process, the action taken depends on the waitflag parameter specified in the SENDMAIL 
intrinsic call. If the mailbox currently is being used by other intrinsics, the SENDMAIL intrinsic 
waits until the mailbox is free and then sends the mail. 

FUNCTIONAL RETURN 

This intrinsic returns one of the following status codes: 

Status Returned Meaning 







PARAMETERS 



pin 



The mail was transmitted successfully. The mailbox 
contained no previous mail. 

The mail was transmitted successfully. The mailbox 
contained mail sent previously that was overwritten 
by the new mail, or contained previous incoming/ 
outgoing mail that was cleared. 

The mail was not transmitted successfully because the 
mailbox contained incoming mail to be collected by 
the sending process (regardless of the waitflag 
setting). 

An error occurred because an illegal pin parameter 
was specified, or a bounds check failed. 

An illegal wait request would have produced a 
deadlock. 

The request was denied because count exceeded the 
maximum mailbox size allowed by the system. 

The request was denied because storage resources for 
the mail data segment were not available. 



integer by value (required) 

An integer specifying the process to receive the mail. If a son process is 
specified, the integer is the Process Identification Number (PIN) of that 
process. If a father process is specified, the integer is zero. 
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count. 



location 



waitflag 



integer by value (required) 

An integer specifying the length of the message, in words, transmitted 
from the sending process' stack. If zero is specified, SENDMAIL 
empties the mailbox of any incoming or outgoing mail. 

logical array (required) 

The array (buffer) in the stack containing the message. 

logical by value (required) 

A word specifying (in bit 15) the action to be taken if the mailbox 

contains mail sent previously : 

TRUE = Wait until the receiving process collects the previous mail 

before sending current mail. (Bit 15 = 1). 
FALSE = Cancel (overwrite) any mail sent previously with the current 

mail. (Bit 15 = 0). 



CONDITION CODES 



CCE 



CCG 



CCL 



Request granted. The mail was sent (the value or 1 is returned to 
SENDMAIL) or the mail was not sent because the mailbox contained 
;™^rr,w mail +" he collected bv the sending process. The value 2 is 
returned to SENDMAIL. 

Request denied because of an illegal count parameter (the value 5 is 
returned to SENDMAIL), or an illegal pin parameter was specified (the 
value 3 is returned to SENDMAIL), or storage for the mail data 
segment was not available (the value 6 is returned to SENDMAIL). 

Request denied because the bounds check revealed that the count or 
location parameters did not define a legal stack area (the value 3 is 
returned to SENDMAIL), or both processes are waiting to send mail 
(the value 4 is returned to SENDMAIL). 



SPECIAL CONSIDERATIONS 



t* „,, U A «/]]i n rt /*^rt*-»«V-iili+T7 -r/i/^miiroH 

jTHJUeoo ixcuiu.j.j.ng v-'o.j^ti.^ij.j.wjf *^^«.".v>». 



TEXT DISCUSSION 

Page 7-11. 
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INTRINSIC NUMBER 78 



Enables the stack analysis facility. 



LV 

SETDUMP(flags); 



PARAMETERS 

flags 



logical by value (required) 

A logical word whose bits specify the following: 

Bit 15 = If on, specifies a DL to Q initial dump. 

Bit 14 = If on, specifies a Q initial to S dump. 

Bit 13 = If on, specifies a Q-63 to S dump. This bit is ignored if bit 14 
is on. 

Bit 12 = If on, causes an ASCII dump of the octal content along with 
the octal values. 

A value for flags results in a display of registers and stack marker 
trace only. 



CONDITION CODES 

CCE Request granted. 



CCG 



CCL 



Abort stack analysis facility already enabled before SETDUMP call. The 
facility is now set up according to new specifications from this call. 

Not returned by this intrinsic. 



TEXT DISCUSSION 

MPE DEBUG/Stack Dump Reference Manual. 
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Sets bits in the system job control word ( JCW) 



INTRINSIC NUMBER 72 



LV 
5ETJCW0 ■•■ 



You can establish the bit contents of the system job control word (JCW) with the SETJCW intrinsic. 



PARAMETERS 

word 



logical by value (required) 

A 16-bit word whose contents are established by the user for inter- 
process communication. The form is: 



1 



15 



S 



Bit zero is reserved for MPE and should be set to 0. If you set this bit to 
1, the system will output the following message when the user program 
terminates, either normally or due to an error: 

PROGRAM TERMINATED IN ERROR STATE (CIERR 976) 

A batch job is terminated unless the CONTINUE command is used. 
(See the MPE Commands Reference Manual). Bits 1 through 15 may be 
used for any purpose (see the description on page 4-46). 



CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 

Page 4-46 
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STACKDUMP 



INTRINSIC NUMBER 77 



Dumps selected parts of stack to a file. 



HJ\ 



or (from SPL only) 
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SrTACKDUMP'ifilerutmeMnumber.fiagsjelec); 



PARAMETERS 

filename 



idnumber 



flags 



selec 



byte array (optional) 

Contains the file name of the file where the information is to be dump- 
ed. When filename contains the formal designator of the file, the file 
will be opened and closed by the STACKDUMP intrinsic. If the secon- 
dary entry point (STACKDUMP') is used to enter this intrinsic, MPE 
assumes that filename(O) contains the file number of a file which has 
been successfully opened prior to the call to STACKDUMP. In this case, 
the file is not closed before returning to the calling program. When a 
file number is passed via the STACKDUMP' secondary entry point, the 
record length must be between 32 and 256 words and write access must 
be allowed for the file. 

Default: Dump is sent to $STDLIST. 

integer (optional) 

An integer which is displayed in the header of the dump to identify the 

printout. 

Default: Identifying integer not displayed. 

logical (optional) 

A logical value used to specify the following options: 

Bit 15 = Suppress ASCII dump. 

Bit 14 = Suppress trace back of stack markers. 

Default: If bits 14 and 15=00, a corresponding ASCII dump is pro- 
vided for all values dumped in octal, and a trace back of stack 
markers is displayed. 

double array (optional) 

Specifies which stack areas are to be dumped. The format of the array 
is shown in the MPE DEBUG/Stack Dump Reference Manual. The array 
has no predetermined length; the first double word containing the values 
0/-1 indicates the end of the array. An entry for which the count is is 
interpreted as a "skip" (i.e., go to next double word element in list). 

Default: If missing, or if the first double word contains 01-1 (indicat- 
ing end of array), no dump occurs (except for the header), 
unless flags bit 14=0, in which case the trace back of stack 

markers is displayed. 
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STACKDUMP 



COND!T!ON CODES 

CCE Request granted. 

CCG Request denied. Bounds violation occurred and the dump was not 

completed. Record size was not between 32 and 256 words. 

CCL Request denied. File system error occurred during opening, writing to, 

or closing the file. The file error number is returned in idnwnber. 

TEXT DISCUSSION 

MPE DEBUG/Stack Dump Reference Manual. 
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SUSPEND 

INTRINSIC NUMBER 103 Suspends a process. 



LV IV 0-V 
SVSVEND(susp,rin); 



A process can suspend itself with the SUSPEND intrinsic. When this intrinsic is executed, the 
process relinquishes its access to the central processor unit until reactivated by an ACTIVATE 
intrinsic call. When a process suspends itself, it must specify the anticipated source of this 
ACTIVATE call (its father or a son process). When the process is reactivated, it begins execution 
with the instruction immediately following the SUSPEND call. 

PARAMETERS 

susp logical by value (required) 

A word whose 14th and 15th bits specify the anticipated source of the 

call that later will reactivate the process. For processes run by users 

with only the Process Handling Capability, at least one of these bits 

must be set to 1. 

If bit 15 = 1, the process expects to be activated by its father. 

If bit 14 = 1, the process expects to be activated by one of its sons. 

If both of these bits = 1, the suspended process can be activated by 

either father or sons. 

"'" integer by value (optional) 

An integer specifying a Resource Identification Number (RIN). If rin is 
specified, it represents a local RIN that is locked by the process but 
that will be released when this process is suspended. This facility can be 
used to synchronize processes within the same job. 
Default: If omitted, no RIN is unlocked when the process suspends. 

CONDITION CODES 

CCE Request granted. 

CCL Request denied because the susp parameter is not valid, the specified 

RIN is not owned by this process, or the specified RIN was not locked. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

Process Handling Capability required. 

TEXT DISCUSSION 

Page 7-8. 
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SWITCHDB 



Switches BE register pointer. INTRINSIC NUMBER 139 



.' 0-P 



The SWITCHDB intrinsic changes the DB register so that it points to the base of an extra data 
segment instead of the base of the stack. 

FUNCTIONAL RETURN 

This intrinsic returns the logical index of the data segment indicated by the previous DB register 
setting, thus allowing you to restore this setting later. If the previous DB setting indicated the stack, 
zero is returned. 

PARAMETERS 

index logical by value (required) 

Specifies the logical index of the data segment to which the DB register 
is to be switched, as obtained through the GETDSEG intrinsic call. 
MPE checks the value specified for index to insure that the process has 
acquired access to this segment previously. For an extra data segment, 
index must be a positive, non-zero integer. To switch back to the stack 
segment, index must be zero. 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because an illegal data segment was specified. 

SPECIAL CONSIDERATIONS 

Must be running in Privileged Mode. 

TEXT DISCUSSION 

Page 9-5. 
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TERMINATE 



INTRINSIC NUMBER 60 Terminates a process. 



A process and all of its descendants, including any extra data segments belonging to them, can be 
deleted by using the TERMINATE intrinsic. 

All files still open by the process are closed and assigned the same disposition they had when 
opened. 

CONDITION CODES 

The process that calls this intrinsic is terminated and no return is made. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

TEXT DISCUSSION 

Page 4-20 
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TIMER 



Returns system timer. INTRINSIC NUMBER 40 



A 31-bit logical quantity representing the current system timer and overflow count can be returned 
to your program with the TIMER intrinsic. 

The resolution of the system timer is one millisecond. Thus, readings taken within a one-millisecond 
period may be identical. 

FUNCTIONAL RETURN 

This intrinsic returns a 31-bit logical quantity representing the actual millisecond count since the 
midnight preceding the last system cold load. 

CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

I ^^^^ 1 w^ff ■ ^J \^ ^J %q* *■* i *»** ! = 

Page 4-42. 
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UNLOADPROC 



INTRINSIC NUMBER 81 Dynamically unloads a library procedure. 



rv 

UNLOADPROQ/vortrf); 



The UNLOADPROC intrinsic dynamically unloads a procedure and its referenced external 
procedures. 

PARAMETERS 

procid integer by value (required) 

A word containing the procedure's identity number, which was 
obtained from the LOADPROC intrinsic call. 

CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because of invalid procid. 

TEXT DISCUSSION 

Page 4-3. 
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UNLOCKGLORIN 



Unlocks a global RIN. INTRINSIC NUMBER 35 



IV 



The UNLOCKGLORIN intrinsic unlocks a global Resource Identification Number (RIN) that has 
been locked with the LOCKGLORIN intrinsic. 

PARAMETERS 

rinnum integer by value (required) 

A word supplying the number of any RIN locked by the calling process. 
If rinnum does not specify a RIN locked by the calling process, no 
action is taken. 

CONDITION CODES 

CCE Request granted. 

cc q Request denied because this RIN was not locked for this process. 

CCL Request denied because the specified RIN was not allocated. 

TEXT DISCUSSION 

Page 6-3. 
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UNLOCKLOCRIN 



INTRINSIC NUMBER 33 Unlocks a local RIN. 



rv 

UNLO< KLOCN N ritmum) 



The UNLOCKLOCRIN intrinsic unlocks a local Resource Identification Number (RIN) that has 
been locked by the LOCKLOCRIN intrinsic. 

PARAMETERS 

rinnum integer by value (required) 

A word supplying the locked RIN, designated by an integer from 1 to 
the value specified in the rincount parameter of the GETLOCRIN 
intrinsic call. 

CONDITION CODES 

CCE Request granted. 

CCG Request denied because the RIN specified is not locked by the calling 

process. 

CCL Request denied because the specified RIN is not allocated to this 

process. 

TEXT DISCUSSION 

Page 6-8. 
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WHO 



Returns user attributes. 



INTRINSIC NUMBER 69 
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The WHO intrinsic supplies the access mode and attributes of the user running the program. 

PARAMETERS 



mode 



capability 



File access 
attributes 



logical (optional) 

A word to which the current user's access mode is returned. In this 

word, the bits will have the following meanings: 

Bit (15:1) 

1 = The job/session input file and job/session list file form an 
interactive pair. A dialog can be established between a program, 
displaying information on the list device, and a person responding 
through the input device. 

= The job/session input file and job/session list file are not 

interactive. 

Bit (14:1) 

1 = The job/session input file and job/session list file form a 

duplicative pair. Images on the input device are duplicated 
automatically on the list device. 

= The job/session input file and job/session list file are not 

duplicative. 

Bits (12:2) 

01 = The user is accessing the system through a session. 
10 = The user is accessing the system through a job. 

Bits (0:12) - Reserved for MPE. The WHO intrinsic sets these bits to 

zero. 

Default: The user's access mode is not returned. 

double (optional) 

A double word to which the user's file access, user, and capability class 

attributes are returned. In the first word, possession of the following 

file access and user attributes is indicated by the corresponding bit 

being on (equal to 1). 

(Bit (15:1) = Ability to save files (declare them permanent) (SF). 
{ Bit (14:1) = Ability to acquire non-sharable devices (ND). 

Bit (13:1) = Communications System. (CS) 

Bits (9:4) = Reserved for MPE. The WHO intrinsic sets these bits to 
zero. 

Bit (8:1) = User Logging (LG) 

Bit (7:1) = Volume set usage (UV). 

Bit (6:1) = Volume set creation (CV). 
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WHO 



User 
Attributes 



Bit (5:1) = System supervisor (OP). 
Bit (4:1) = Diagnostician (DI). 
Bit (3:1) = Group librarian (GL). 
Bit (2:1) = Account librarian (AL). 
Bit (1:1) = Account manager (AM). 
Bit (0:1) = System manager (SM). 

In the second word, possession of the user's capability -class attributes is 

indicated by the corresponding bit being on (equal to 1). 

Bit (15:1) = Process handling (PH). 

Bit (14:1) = Extra data segments (DS). 

Bit (13:1) = Reserved for MPE. The WHO intrinsic sets this bit to zero. 

Bit (12:1) = Exclusive simultaneous use of more than one system re- 
source (Multiple RIN's) (MR). 

Bits (10:2)= Reserved for MPE. The WHO intrinsic sets these bits to 
zero. 

Bit (9:1) = Privileged mode operation (PM). 

Bit (8:1) = Interactive (session) access (IA). 

Bit (7 :1) = Batch (job) access (BA). 

Bits (0:7)= Reserved for MPE. The WHO intrinsic sets these bits to 
zero. 

Default: The user's file access, user, and capability -class attributes are 
not returned. 



lattr 



usern 



double (optional) 

A double word to which is returned the local attributes of the user, as 

defined by a user with the Account Manager attribute. 

Default: The user's local attributes are not returned. 

byte array (optional) 

An 8-byte array to which the user's name is returned. 

Default: The user's name is not returned. 



groupn 



byte array (optional) 

An 8-byte array to which the name of the user's log-on group is 

returned. 

Default: The user's log-on group is not returned. 



acctn 



homen 



byte array (optional) 

An 8-byte array to which the name of the user's log-on account is 

returned. 

Default: The user's log-on account is not returned. 

byte array (optional) 

An 8-byte array to which the name of the user's home group is returned. 
If a home group was not assigned, this array is filled with blanks. 
Default: This information is not returned. 



termn 
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logical (optional) 

A word to which the logical device number of the job/session input 

device is returned. 

Default: The logical device number is not returned. 



WHO 



CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 

Page 4-10. 
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WRITELOG 



INTRINSIC NUMBER 211 



Writes a record to a logging file. 



i! UA I I I 

WRFF&LQQ (index, data, ten. mode t status); 



The WRITELOG intrinsic journalizes data base and subsystem file additions and modifications to 
logging tape or disc files. 



PARAMETERS 

index 
data 



len 



mode 



status 



double (required) 

The parameter returned from OPENLOG that identifies your access to 

the logging file. 

logical array (required) 

The array in which the information to be logged is passed. The maxi- 
mum length of the data is 32K words. A log record contains 128 words 
of which 119 are available to you. If you specify a length greater than 
119 words a continuation record is automatically posted for you. The 
most efficient use of the log file is a multiple of 119 words. 

integer (required) 

The length of the data in data. A positive number indicates words, 

and a negative number indicates bytes. If the length is greater than 119 

words, the information in data is divided into two or more physical log 

records. 

integer (required) 

An integer which you use to indicate whether or not your process 
should be suspended if your request for service cannot be completed 
immediately. Enter a zero if you want to wait for service, enter a one if 
you do not want to wait. 

integer (required) 

An integer which indicates logging system errors to you. (See table 

10-12, User Logging Error Messages.) 



CONDITION CODES 

The condition code remains unchanged. 

TEXT DISCUSSION 

Page 10-93 
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XARiTRAP 



Enables the user- written software arithmetic trap. 



INTRINSIC NUMBER 50 



!\ 



The XARITRAP intrinsic enables you to replace the trap handler in MPE with your own trap 
handler routine. 



PARAMETERS 

mask 



plabel 



oiamaSK 



integer by value (required) 

A word mask that selects which hardware traps will invoke the software 
trap, and which will not. Only the 14 rightmost bits of the word form- 
ing the mask are used. The setting of the other bits is not significant, 
but it is recommended that they be set to zero. Thus, octal values up 
to %37777 are allowed for this parameter. 

If a bit is on (= 1), the corresponding hardware trap activates the soft- 
ware trap. If a bit is off (= 0), the corresponding hardware trap does not 
activate the software trap. If all bits are set to zero, the software trap 
is disabled. 



Bit 



Hardware Error Trap 



15 Floating point divide by zero. 

14 Integer divide by zero. 

13 Floating point underflow, 

12 Floating point overflow. 

11 Integer overflow. 

10 Extended precision overflow. 

9 Extended precision underflow. 

8 Extended precision divide by zero. 

7 Decimal overflow. 

6 Invalid ASCII digit. 

5 Invalid decimal digit. 

4 Invalid source word count. 

3 Invalid decimal operand length. 

2 Decimal divide by zero. 

integer by value (required) 

The external-type label of the user's trap procedure. If the value of this 
entry is 0, the software trap is disabled. The external-type label of the 
procedure, which resides in the segment transfer table of the proce- 
dure's code segment, is passed as a parameter (in SPL) by placing a @ 
before the procedure name. 

«' ■•— + r* 1-f.nia /«/inTii'i"/irJ 1 

A word in which the value of the previous mask is returned to the user's 
program. 
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XARITRAP 



oldplabel integer (required) 

A word in which the previous plabel is returned to the user's program. 
If no plabel existed previously, zero is returned. 

CONDITION CODES 

CCE Request granted. Software trap enabled. 

CCG Request granted. Software trap disabled. 

CCL Request denied because of an invalid plabel. 

NOTE 

The validity of a trap procedure, specified by the external- 
type label of the user's trap procedure (plabel), depends on 
the code domain of the caller's code and executing mode 
(privileged or non-privileged), and on the code domain of the 
plabel and the mode (privileged or non-privileged). The code 
domains are: 

PROG (User Program) 

GSL (Group SL) 

PSL (Public SL) 

SSL (System SL, non-MPE segments) 

MPESSL (System SL, MPE segments) 

If, when a trap procedure is being enabled, the code of the 
caller is 

1. Non-privileged in PROG, GSL, or PSL, plabel must be 
non-privileged in PROG, GSL, or PSL. 

2. Privileged in PROG, GSL, or PSL, plabel may be 
privileged or non-privileged in PROG, GSL, or PSL. 

3. Privileged or non-privileged in SSL, plabel may be in any 
non-MPESSL segment. 

TEXT DISCUSSION 

Page 4-32. 
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XCONTRAP 

Enables or disables the CONTROL-Y trap. INTRINSIC NUMBER 54 



111 



When a session is initiated, the CONTROL-Y trap is disabled. The XCONTRAP intrinsic enables this 
trap. This intrinsic takes effect on the file $STDINX, and also on $STDIN (when $STDIN is defined 
as a terminal). 

PARAMETERS 

plabel integer by value (required) 

The external-type label of the user's trap procedure. If the value of this 
entry is 0, the software trap is disabled. 

oldplabel A word in which the previous plabel is returned to the user!s program. 

If no pla bel existed previously, zero is returned. 

CCE Request granted. Trap enabled. 

Ccg Request granted. Trap disabled. 

CCL Request denied because of illegal plabel, or because $STDIN is not 

defined as a terminal. 

NOTE 

The validity of a trap procedure, specified by the external- 
type label of the user's trap procedure (plabel), depends on 
the code domain of the caller's code and executing mode 
(privileged or non-privileged), and on the code domain of the 
plabel and the mode (privileged or non-privileged). The code 
domains are: 

PROG (User program) 

GSL (Group SL) 

PSL (Public SL) 

SSL (System SL, non-MPE segments) 

IVIIT-CjOOIj yujoucm uj-i, nix -" ov, & ***~..* w/ 

If, when a trap procedure is being enabled, the code of the 

caller is 

1. Non-privileged in PROG, GSL, or PSL, plabel must be 
non-privileged in PROG, GSL, or PSL. 

2. Privileged in PROG, GSL, or PSL, plabel may be 
privileged or non-privileged in PROG, GSL, or PSL. 

3. Privileged or non-privileged in SSL, plabel may be in any 
non-MPESSL segment. 

TEXT DISCUSSION 

Page 4-41. 
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XLIBTRAP 

INTRINSIC NUMBER 52 Enables or disables the software library trap. 

IV [ 



m 



When a program begins execution, the software library trap is disabled automatically. You can 
enable (or subsequently disable) this trap with the XLIBTRAP intrinsic call. 

PARAMETERS 

plabel integer by value (required) 

The external-type label of the user's trap procedure. If the value of this 
entry is 0, the trap is disabled. 

oldplabel integer (required) 

A word in which the previous plabel is returned to the user's program. 
If no plabel existed previously, zero is returned. 

CONDITION CODES 

CCE Request granted. Trap enabled. 

CCG Request granted. Trap disabled. 

CCL Request denied because of an illegal plabel. 

TEXT DISCUSSION 

Page 4-35. 
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XSYSTRAP 



INTRINSIC NUMBER 53 
Enables or disables the system trap. 
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When a program begins execution, the system trap is disabled automatically. When enabled by the 
XSYSTRAP intrinsic, and subsequently activated by an error, the trap transfers control to a trap 
procedure. 

You can enable (or subsequently disable) the system trap by using the XSYSTRAP intrinsic. 

PARAMETERS 

plabel integer by value (required) 

The external-type label of the user's trap procedure. If the value of this 
entry is 0, the software trap is disabled. 

oldplabel integer (required) 

A word in which the previous plabel is returned to the user's program. 
If no plabel existed previously, zero is returned. 

CONDITION CODES 

CCE Request granted. Trap enabled. 

CCG Request granted. Trap disabled. 

QCL Request denied because of an illegal plabel. 

TEXT DISCUSSION 

Page 4-36. 
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INTRINSIC NUMBER 136 



Changes size of Z to DB area. 



1 



II 



The ZSIZE intrinsic alters the size of the current Z to DB area by adjusting the register offset of the 
Z address from the DB address (Z to DB). 

The ZSIZE intrinsic moves the Z address forward (expansion) or backward (contraction). If the Z 
to DB area size requested exceeds the maximum size permitted for the Z to DL (stack) area, only 
the maximum size allowed is granted. 

All changes to the Z to DB area are made in increments or decrements of 128 words, and hence the 
size actually granted may differ from the size requested. 

FUNCTIONAL RETURN 

This intrinsic returns the size actually granted. 

PARAMETERS 



size 



integer by value (required) 

An integer value greater than or equal to zero that specifies the desired 

register offset (in words) for Z to DB. 



CONDITION CODES 

CCE Request granted. 



CCG 



CCL 



The requested size exceeded the maximum limits of the Z to DL (stack) 
area. The maximum limit is granted, and this value is returned to the 
calling process as the value of ZSIZE. 

An illegal size parameter, less than (S — DB) + 64 words, was specified. 
This minimum value is assigned by default. 



TEXT DISCUSSION 

Page 4-27. 
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INTERPROCESS COMMUNICATION AND 
CIRCULAR FILES 



SECTION 



INTRODUCTION 

Interprocess communication (IPC) is a facility of the file system which permits multiple user pro- 
cesses to communicate with one another in an easy and efficient manner. To accomplish this, IPC 
uses message files as the interface between user processes. These message files act as first-m-first-out 
queues of records, with entries made by FWRITEs and deletions made by FREADs: one process 
may submit records to the file with the FWRITE intrinsic while another process takes records from 
the file using FREADs. 

Occasionally a process may attempt to read a record from an empty message file or write a record 
to a message file that is full. In such situations, the file system will usually cause the process to wait 
until its request can be serviced; that is, until another process either writes a record to the empty 
file or reads enough records to take a block from the full file. 

, _ - . » j. „ r^j^_____ „ ~~:. Tn -» nv^/tacc or»rJ o moccaap flip! a TYTQCeSS 
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opening the file with read access, identified as a "reader", may only read from the file and not 
write- a process opening the file with write access, identified as a "writer", may only write to the 
file and not read. (If it is necessary for the same process to read and write, it may open the message 
file'twice once as a reader and once as a writer.) More than one message file may be associated with 
a process, and the process may be configured as a reader to some of the files and as a writer to 
others. A given message file typically has one reader, though more are allowed, and one or more 
writers. 

Applications for IPC exist wherever it is necessary for processes to communicate with one another. 
In the case of a father process with several sons, message files may serve as interfaces between the 
processes: through one file, the father may direct the activities of the sons; through another, the 
sons may inform the father of their progress. Message files may also aid object managers during 
data base operations: several writers may send information to a file which serves as the single source 
from which the data base process actually receives the information. 

OPERATION 

Message files are maintained and manipulated by several intrinsics. The FOPEN, FREAD, FWRITE, 
FCONTROL, and FCLOSE intrinsics operate upon the files to yield a unidirectional, iirsL-m-urs„- 
out message queue. 

FOPEN Establishes a connection to a message file. With FOPEN, a user process 

identifies itself as either a reader or writer; readers access the head of 
the message file and writers access the tail. Incompatible parameters 
that are specified with FOPEN are adjusted. For example, since messages 
are read or written to the file one record at a time, a multirecord param- 
eter is corrected. If FOPEN is used to access a new file, a new message 
file is created. 
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NOTE 

There are different Access Type (bits (12:4) of the Access 
Options) specifications for slightly different types of writer 
processes. In one case, if a writer is the first accessor to a 
message file, the file's contents are purged; in another case, 
the writer simply appends records to the tail of the file. 
These AOPTIONS are discussed in a later section. 



FREAD 



Reads one record from the head of a message file. The record is copied 
to the reader's TARGET area and is logically deleted from the message 
queue; the next record is now at the head of the file. If a process tries 
to read from an empty message file which writers are accessing, the file 
system causes it to wait until a writer process enters a record to the file; 
if there are no writers associated with the message file, an end-of-file 
indication, CCG, is returned. 



NOTE 

If the message file is empty and there are no writers, the 
process will wait if there is an FCONTROL 45 in effect, or 
if this is the first FREAD after the reader's FOPEN. 



FWRITE 



Appends one record to the tail of a message file. If a process tries to 
write to a full message file which readers are accessing, the file system 
causes it to wait until a reader process has read a block of records from 
the file; if there are no readers associated with the message file, an end- 
of-file indication, CCG, is returned. 



NOTE 

If the message file is full and there are no readers, the pro- 
cess will wait if there is an FCONTROL 45 in effect, or if 
this is the first FWRITE after the writer's FOPEN. 



FCONTROL 



Supplies various control functions during a process that is using a 
message file. These control functions permit a process to take advantage 
of the additional features of IPC, which are discussed in detail in the 
next section. 



FCLOSE 



Breaks a process' connection with a message file. If the process reopens 
the same file later, it may do so as either a reader or a writer, regardless 
of what it was previously. 



ADDITIONAL FEATURES 



Besides the regular attributes of IPC and message files, several features are available for use with 
these facilities. Writer ID's and nondestructive reads are specifically intended for use with IPC; copy 
access, the global multiaccess option and the ability to append to variable-length files are general 
enhancements to the file system. The time-out feature has been expanded to apply to IPC. 
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Writer ID's. When a writer process opens a message file, the file system assigns a unique 18-bit ■ 
ID number to the writer. Each record the process writes to the message file is prefixed with this 
number by FWRITE. When the writer closes the file, the ID number is no longer associated with the 
process and may be reused. Whenever a writer opens or closes a message file, records are written to 
the file indicating these actions. Record prefixes and open/close records are usually transparent to 
the readers of the message file, but by issuing an FCONTROL 46, the reader process may see them. 
The interested reader may use the writer ID's to determine the source of the records it is receiving. 

Time-outs. A reader or a writer process may limit the length of time it will wait to be serviced. By I 
issuing an FCONTROL 4, a reader may specify the maximum number of seconds it will permit the 
file system to keep it waiting for a record to be written to an empty message file; a writer may also 
use FCONTROL 4 to specify the maximum number of seconds it will wait for a block of records to 
be read from a full file. 

Copy access. When records are read from a message file, FREAD logically deletes them as it reads. I 
In order to copy a message file without destroying it, the file must be opened with the file copy 
option specified in the AOPTIONs of the FOPEN, or the COPY keyword may be specified in a 
FILE equation. When this option is selected, the message file is treated as a standard sequential 
file rather than as a message queue, and may be copied safely. The file may then be read by logical 
record or by block, and information may be written to it by block. 

NOTE 

In order to access a message file in copy mode, a process must 
have exclusive access to the file. 

Nondestructive read. By issuing an FCONTROL 47, a reader may avoid deleting the next record it 1 
reads; the record will remain at the head of the message queue. This feature differs from the copy 
access feature in that it is a temporary condition: the second FREAD following the FCONTROL 47 
will reread the record and delete it in the usual manner. 

Global multiaccess. When the global multiaccess option is requested, processes located in different | 
jobs or sessions may open the same file. The global multiaccess option may be requested in the 
AOPTIONs of the FOPEN to the file, or by using the GMULTI keyword in a FILE command to 
create the file. 

NOTE 



Global multiaccess is unavailable to message files when they 
have been opened with exclusive access in copy mode. 

Appending to variable -length files. Variable -length files may be opened with append access. It is 
not necessary to have fixed -length records of the maximum possible size, so space is conserved. 

USING IPC 

Message files can be created in several ways. When a user process opens a new file and indicates in 
the FOPTIONs that it will be a message file, the FOPEN intrinsic creates the new message file. In 
order to create a message file with the BUILD command, use the MSG keyword; for example, to 
build a message file named SARA, enter: 

:BUILD SARA; MSG 
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A new message file may also be specified with a FILE command. Use the MSG keyword for a new 
file: 

:FILE LISBETH, NEW; MSG 

A message file named LISBETH is indicated. 

When you perform a LISTF.2 command, message files will be identified by an "M" in the third 
column of the TYP field ; SARA is identified here : 

FILENAME CODE LOGICAL RECORD SPACE 

SIZE TYP EOF LIMIT R/B SECTORS #X MX 

SARA 1£8W VBM 1031 1 258 1 8 

Other types of files are similarly indicated by a token in the TYP field: 

K — identifies a KSAM file 

R — identifies a Relative I/O file 

O — identifies a Circular file 

A blank in the third column indicates a standard MPE file. Circular files are discussed in a later 
section. 

Occasionally, you might create a message file and specify a certain number of records for the file to 
contain, only to discover that the file system has allocated more records for the file than you 
requested. The reason for this is that the file system is maintaining the necessary internal structure 
for the message file. The file system has four basic rules for establishing this structure when the 
message file is created : 

1 Since records are written to the message file every time a writer process opens or closes the file, 
the file system adds two records to the requested number to allow for a minimum of one open 
and one close operation. 

2 The requested number of records is rounded up to fill an even number of blocks. 

3 The file system adds an extra block to the message file for the file label to occupy. (This block 
is transparent to you.) 

4 Each extent is the same size; that is, the file system assigns the same number of blocks to each 
extent. 

For example, suppose you want to create a message file named ODDSIZE: 
:BUILD ODDSIZE; MSG; REC=,3; DISC=51,8 

You have specified a message file with fifty-one records, three records per block, that occupies 
eight extents. The file system will adjust the number of records to conform to the rules for message 
file structure: 

The file system adds two records to allow for one open and one close indication; the number 
of records goes from 51 to 53. 

The number of records is rounded up to 54 to provide an even number of blocks. With three 
records per block, 54 records will fill 18 blocks. 
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An additional block is added to the file to accommodate the file label. Now the file contains 
19 blocks. 

The eight extents must all be the same size, so the number of blocks is increased from 19 to 24. 
Each extent now contains three blocks. 

Of the 24 blocks in ODDSIZE, 23 are data blocks and one contains the file label, which is invisible 
to you. With three records per block, 23 blocks contain a total of 69 data records! 

FEATURES OF INTRINSICS FOR MESSAGE FILES 

There are a few features of several intrinsics which apply specifically to message files. Most of these 
features are found in FOPEN and FCONTROL, but several other intrinsics are also affected. 

Certain intrinsics are not allowed for message files,* These intrinsics are listed in Table 3-1: 

Table 3-1. Intrinsics that are not permitted with message files. 



FPOINT 
FREADSEEK 
FUPDATE 
FDELETE 



FREADDIR 

FSPACE 

FWRITEDIR 



*The FSETMODE intrinsic is permitted, but ignored. 

Parameters that are omitted in the following descriptions retain their normal range of values and 
their normal default values. 



FOPEN 

FOPTIONS: 



(2:3) 



File type. Determines the type of file to create for a new file. 
If the file is old, this field is ignored. 

000 — Ordinary file 

001 - KSAM file 



uiu — rteiauve i/«~» iub 



100 — Circular file; discussed in the next section 
110 —Message file 

NOTE 

The Default Designator FOPTION, bits 10 through 12, offers 
several choices for default file designators. Any value used 
other than for "filename" will override the File Type field. 

(8:2) — Record format. Message files are always internally formatted 
as variable-length records. However, a message file can appear 
as a fixed file to an opener. There is no difference for a writer, 
but a reader will have the portion of his target area which ex- 
ceeds the file filled with blanks (for an ASCII file) or zeroes 
(for a binary file.) 



00- Fixed 

01 — Variable 

10 — Undefined, changed to variable 

AOPTIONS: (3:1) — File copy. This feature permits a message file to be treated as 

a standard sequential file, so it can be copied by logical record 
or physical block to another file. 

— The file will be accessed in its native mode; that is, a 

message file will be treated as a message file. 

1 — The file is to be treated as a standard, sequential file with 

variable-length records. This allows nondestructive read- 
ing of an old message file at either the logical record or 
physical block level. Only block level access is permitted 
if the file is opened with write access. These blocks are 
checked for proper message file format to prevent in- 
correctly formatted data from being written to the 
message file while it is unprotected. 

NOTE 

In order to access a message file in copy mode, a process 
must have exclusive access to the file. 

Setting this bit on causes all the remaining file parameters 
to have their normal defaults. 

(5 :2) — Multiaccess mode. This feature permits processes located in 
different jobs or sessions to open the same file. 

00 — No multiaccess. The file system changes this value to 2 

to allow global multiaccess. 

01 — Only intra-job multi-access allowed; this is the same as 

specifying the MULTI option in a FILE command. 

10 — Inter-job multi-access allowed; this is the same as speci- 

fying the GMULTI option in a FILE command. 

11 — Undefined. If this is specified, the FOPEN will be re- 

jected with an error code of 40: ACCESS VIOLATION. 

(7:1) — Inhibit buffering. For message files, the file system sets this bit 
off. 

NOTE 

Readers may open a message file with NOBUF if they are in 
copy mode; this determines whether they will be accessing 
the file record by record or block by block: 

— read by logical record 

1 — read by physical block 
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(8:2)- 



Writers must open message files with NOBUF if they are in 
copy mode; they will access the file block by block. 

Exclusive. The values for this field are the same as for any 
disc file, but they have different meanings for the readers and 
writers of a message file: 



USER 




VALUE 


Means 


EXCLUSIVE 


One reader, one writer 


SEMI 


One reader, multiple writers 


SHARE 


Multiple readers and writers 


Default 


One reader, one writer 



(11 :1) — Multirecord. For message files, the file system sets this bit to 
0. 



NUMBUFFERS: 



FILESIZE: 



(12:4) — Access type. These bits specify whether the user will be a 
reader or a writer process. 

0000— READ access only. The FWRITE intrinsic cannot 
reference this file. This access type requires both read 
and write access capability to the file. A process that 
has opened a file with this access type is a "reader". 

0001 —WRITE access only. If this is the first accessor to the 
file and the process has write access capability, then 
the file's contents are purged. If this is not the first 
accessor to the file, the file system sets this access 
type to APPEND. The FREAD intrinsic cannot 
reference this file. A process that has opened a file 
with this access type is a "writer". 

0010 —WRITE SAVE access. The file system sets this to 

APPEND access. 

0011 —APPEND access only. The FREAD intrinsic cannot 

reference this file. This access type requires append 
capability to the file. A process that has opened a 
file with this access type is a "writer". 

This field is relevant only if this is a new file. The DEVICE field must 
either be omitted or specify a disc; specification of any device other 
than a disc opens the device. When this happens, the file is no longer a 
message file. 

(0:11) — Ignored. 

(11:5) — Value between 2 and 31; default is 2. This parameter must 
not exceed the physical record capacity of the file. 

The number of records is rounded up to completely fill the last block 
and to make the last extent the same size as the other extents. Two 
additional records are included for the open and close records. 
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FCONTROL 



A few controlcodes deal specifically with IPC. Those not mentioned here are invalid when IPC is 
being used. 



CONTROL- 
CODE 

2 

3 

4 



PARAM DESCRIPTION 



integer 



43 
45 



46 



TRUE 



FALSE 



TRUE 



FALSE 

47 TRUE 

FALSE 



Complete all I/O; ignored in the case of message files. 

Read hardware status word. 

Set time-out interval. This applies to both FREADs and FWRITEs. 
The time-out will be armed at the beginning of the I/O request and 
cleared when the I/O completes. PARAM specifies the length of the 
time-out in seconds. A value of zero disables time-outs on the file. 

Write end-of-file. Used only to verify the state of the file by writing out 
the file label and buffer area to disc; this ensures that the message file 
can survive system crashes. No EOF is written. 

A CCG condition code is returned if an outstanding I/O operation has 
completed. An IOWAIT must be issued to finish the request. 

Enable extended wait. Permits a reader to wait on an empty file that is 
not currently opened by any writer, or a writer to wait on a full file 
that has no reader. This FCONTROL will remain in effect until 
FCONTROL 45 is issued with a PARAM value of FALSE. 

Disable extended wait. Specifies that when an FREAD encounters an 
empty file that has no writer, or an FWRITE encounters a full file that 
has no reader, it will return an end-of-file condition. (Default) 

Enable reading the writer's ID. Each record read will have a two-word 
header. The first word will indicate the type of record: 

- data record 

1 - open record 

2 - close record 

The second word will contain the writer's ID number. If the record is a 
data record, the data will follow the header; open and close records 
contain no more information. 

Disable reading the writer's ID. Only data is read to the reader's 
TARGET area. The open and close records are skipped and deleted by 
the file system when they come to the head of the message queue, and 
the two-word header is transparent to the reader. (Default) 

Nondestructive read. The next FREAD by this reader will not delete 
the record. Subsequent FREADs will be unaffected. 

The next FREAD by this reader will delete the record. (Default) 



FCHECK 



There is one error message that is returned only when using IPC: 
151 CURRENT RECORD WAS LAST RECORD WRITTEN BEFORE SYSTEM CRASHED, 

This message is returned when this record is read following system startup. 
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FGETINFO 

The value returned in RECSIZE will indicate the user's data record size, and the value returned in 
EOF will indicate the number of data records, unless an FCONTROL 46 is in effect. When an 
FCONTROL 46 is in effect, the value returned in RECSIZE will be the size of the user's data 
records, including the two-word header; the number of records returned in EOF will include open, 
close and data records. 

The value returned in BLKSIZE reflects the actual blocksize of the file. When the file is created, 

the blocksize is computed by the following algorithm: 

BLOCKSIZE := (( RECORDSIZE + 3 ) * BLOCKING FACTOR ) + 2 

where RECORDSIZE and BLOCKSIZE are in words. For example, with a recordsize of 100 words 
and a blocking factor of 10, the blocksize would be 1032 words. 



FFILEINFO 

Two values for ITEMVALUE are specifically for use with IPC: 
ITEM # TYPE DESCRIPTION 

34 integer The current number of writers. 

35 integer The current number of readers. 

CIRCULAR FILES 

Circular files are wrap-around structures which behave as standard sequential files until they are full. 
As records are written to a circular file, they are appended to the tail of the file; when the file is 
filled the next record added causes the block at the head of the file to be deleted and all other 
blocks to be logically shifted toward the head of the file. Circular files may not be simultaneously 
accessed by both readers and writers. When the file has been closed by all writers, it may be read; 
a reader takes records from the circular file one at a time, starting at the head of the file. 

Circular files are particularly useful as history files, when a user is interested in the information 
recently written to the file and is less concerned about earlier material that has been deleted. These 
history files are frequently used as debugging tools: diagnostic information may be written to the 
file, and the most recent and relevant material can be saved and studied. 

r»^ n « . Pirmlar «« *« similar to creating a message file. When a user process opens a new file and 
indicate in the AOPTIONsthat it will be a circular file, the FOPEN intrinsic creates the new circular 
fUe. In order to create a circular file with the BUILD command, use the CIR keyword; for example, 
to build a circular file named CIRCLE, enter: 

:BUILD CIRCLE; CIR 

A new circular file may also be specified with a FILE command. Use the CIR keyword for a new 

file: 

. — n Aiiti k Mrll . C T D 

ULt KUUNU, new, i. jl n 

A circular file named ROUND is indicated. 

3-9 



When you perform a LISTF,2 command, circular files will be identified by an "0" in the TYP field; 
CIRCLE is identified here : 



FILENAME CODE 



CIRCLE 



LOGICAL RECORD SPACE 

SIZE TYP EOF LIMIT R/B SECTORS #X MX 



128W FBO 



1023 1 



128 1 8 



FEATURES OF INTRINSICS FOR CIRCULAR FILES 

Most intrinsics treat circular files the same way they treat regular disc files, but some have special 
features which apply specifically to circular files. Most of these features are found in FOPEN, but 
a few other intrinsics are also affected. 

Certain intrinsics are not allowed when circular files are used. These intrinsics are listed in Table 3-2: 
Table 3-2. Intrinsics that are not permitted with circular files. 



Not permitted 


Not permitted 


for READ access 


for WRITE access 


FUPDATE 


FUPDATE 


FDELETE 


FDELETE 


FWRITEDIR 


FWRITEDIR 


FWRITE 


FREAD 




FREADDIR 




FREADSEEK 




FPOINT 




FSPACE 



Parameters that are omitted in the following descriptions retain their normal range of values and 
their normal default values. 



FOPEN 
FOPTIONS: 



AOPTIONS: 



(2 :3) — File type. Determines the type of file to create. If the file is old, 
this field is ignored. 

000- Ordinary file 

001 - KSAM file 

010- Relative I/O file 

100- Circular file 

110— Message file 

(5:2)— Multiaccess mode. This feature permits processes located in 
different jobs or sessions to open the same file. 

No multiaccess. For a writer, the file system changes 
this value to a 2 for global multiaccess. 

Only intra-job multiaccess allowed; this is the same as 
specifying the MULTI option in a FILE command. 

Inter-job multiaccess allowed; this is the same as 
specifying the GMULTI option in a FILE command. 



00 



Ol- 



IO 
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11 - Undefined, If this is specified, the FOPEN will be 
rejected with an error code of 40: ACCESS VIO- 
LATION. 

(7 :1 ) _ inhibit buffering. Reader processes may open circular file with 
either the BUF or NOBUF option; for write access to circular 
files, the file system sets this bit off. 

NOTE 
Readers may open a circular file with NOBUF if they are in 
copy mode; this determines whether they will be reading the 
file record by record or block by block: 

— read by logical record 

1 — read by physical block 

(8:2) - Exclusive. The values for this field are the same as for any 
standard disc file, but they have different meanings for the 
readers and writers of a circular file: 



USER Changed to: 

VALUE READER WRITER 

EXCLUSIVE EXCLUSIVE EXCLUSIVE 



SEMI 



SHARE EXCLUSIVE 



SHARE SHARE SHARE 



Default 



SHARE EXCLUSIVE 



For readers, SHARE means "allow other readers"; 
for writers, SHARE means "allow other writers". 

(11:1) — Multirecord. When a reader specifies this option, the file 
will be accessed NOBUF; for writers, this bit is set to zero. 

,^ _ . > . i nm 1_-J._ „ — ~«.P.*t «tV» *v*-V» av +Vt£l UCOT Will Hp fl 

(12:4) — Access type, niese uits oycMiiy nucuiiv! ""v —v- . _- - 

reader or a writer process. 

0000 —READ access only. 

nnr<-t n7T)Trn? „„„„,«. ^^.Ut Tf tViic is thf> first, accessor to 
the file, then the file's contents are purged. If this 
is not the first accessor to the file, the access type 
is set to APPEND. 

0010 —WRITE SAVE access. Set to APPEND access. 

0011 —APPEND access only. 

NOTE 
Circular files allow variable length records with append access. 

Any other access types are invalid. 
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FILESIZE: 
FWRITE 



The number of records is rounded up to completely fill the last block. 



This intrinsic logically appends the user's record to the end of the file. If the file is full, the first 
block is deleted, the remaining blocks are logically shifted to the file's head, and the new record is 
appended to the end of the file. 



FCLOSE 

For circular files, deletion of disc space beyond the end-of-file is not allowed. 

EXAMPLES 

The following programs illustrate the use of IPC via message files. Intrinsics called within the pro- 
grams manipulate the message files to produce a unidirectional flow of information. 

In these two programs, the first is sending information to the second through a message file: the 
first program, PROC1, reads data from a data file and writes it to MSGFILE2; the second program, 
PROC2, can then read this data from MSGFILE2 and print it. When PROC2 finishes reading and 
printing the data, it writes a message to MSGFILE1 indicating this and terminates. PROC1 reads 
this message from MSGFILE1 and also terminates. The messages travel among processes and 
message files as illustrated in Figure 3-1 : 





DATA 








1 
1 
t 








PROC1 






♦ 

1 
1 




1 

1 

t 




MSGFILE1 


MSGFILE2 




1 
1 


1 

1 

♦ 






PROC2 





Figure 3-1. Data paths among processes and message files. 
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SCONTROL USLINIT 

<< Purpose: >> 

<< Read data from a data file and send to another process. >> 

BEGIN 

LOGICAL EOF '= FALSE; 

INTEGER DATA'FILE, LEN, PIN, IN'FILE, OUT'FILE; 
BYTE ARRAY IN'FILE'NAME (0:8) := "MSGFILE1 "; 
BYTE ARRAY OUT ' FILE ' NAME (0:8) := "MSGFILE2 "; 
BYTE ARRAY DATA ' FILE ' NAME (0:8) := "DATA "; 
BYTE ARRAY PRINTPROC (0:8) := "PRNTPROC "; 
ARRAY MESSAGE (0:39); 

INTRINSIC CREATEPROCESS, FCLOSE, FOPEN, FREAD, FWRITE, 
QUITPROG, PRINT, READ; 

<< Create entries for the message files in the directory: >> 

<< Note that IN'FILE'NAME ("MSGFILE1") is opened with FOPTIONs >> 
<< %30004: this indicates a new ASCII message file. >> 

IN'FILE := FOPEN (IN'FILE'NAME, %30Q04); 

IF < THEN QUITPROG (1 ); 

FCLOSE (IN'FILE, 2, 0); << Save file as session temporary. >> 

IF < THEN QUITPROG (2); 

<< Note that OUT ' FILE ' NAME ("MS6FILE2") is opened with FOPTIONs >> 
<< %30004: this indicates a new ASCII message file. >> 

OUT'FILE := FOPEN ( OUT ' FILE ' NAME, %30004) ; 

IF < THEN QUITPROG (3); 

FCLOSE (OUT'FILE, 2, 0); << Save file as session temporary. >> 

IF < THEN QUITPROG (4); 

<< Create and activate the print process: >> 

CREATEPROCESS (, PIN, PRINT'PROC) 
tc • t u c m niiTTPPnc ( S ■) ■ 



« Open message file for traffic from print process: >> 

<< Note that IN'FILE'NAME ("MSGFILE1") is opened with FOPTIONs 
<< %106 and AOPTIONs %1100: %106 indicates an old temporary 
<< ASCII file and %1100 indicates a reader process with 
<< exclusive access and multiaccess capability. MSGFILE1 
<< has already been designated as a message file. Since 
<< only one reader and one writer process will be accessing 
<< the message file, exclusive access mode is specified. 

IN'FILE := FOPEN (IN'FILE'NAME, %106, %1100); 
IF < THEN QUITPROG (7); 

<< Open message file for traffic to print process: >> 



>> 
>> 
>> 
>> 
>> 
>> 
>> 
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<< Note that OUT • FILE • NAME ("MSGFILE2") is opened with FOPTIONs >> 

<< %106 and AOPTIONs %1101: %106 indicates an old temporary >> 

<< ASCII file and %1101 indicates a writer process with >> 

<< exclusive access and multiaccess capability. MSGFILE2 has >> 

<< already been designated as a message file. Since only >> 

<< one reader and one writer process will be accessing the >> 

<< message file, exclusive access mode is specified. >> 

OUT'FILE := FOPEN (OUT • F ILE • NAME, %106, %1101); 
IF < THEN QUITPROG (8); 

<< Open data input file: >> 

<< Note that DATA ' FILE ' NAME ("DATA") is opened with FOPTIONs %3 » 

<< and AOPTIONs 0: %3 indicates an old permanent or temporary >> 

<< file and indicates read only access. The file system >> 

<< will change the FOPTIONs to specify an ASCII file. >> 

DATA'FILE := FOPEN ( DATA ' FILE ' NAME, %3, 0); 
IF <> THEN QUITPROG (9); 

WHILE NOT EOF DO BEGIN 

LEN := FREAD (DATA'FILE, MESSAGE, -80); 
IF < THEN QUITPROG (10); 
IF > THEN EOF := TRUE 
ELSE BEGIN 

FWRITE (OUT'FILE, MESSAGE, -LEN, 0); 
IF <> THEN QUITPROG (11); 
END; 
END << WHILE >>; 



FCLOSE (OUT'FILE, 4, 0); 
IF < THEN QUITPROG (12); 



<< No more data to send: EOF >> 



FREAD (IN'FILE, MESSAGE, 1); 
IF <> THEN QUITPROG (13); 



<< Wait for printing process >> 
<< to finish. >> 



FCLOSE (IN'FILE, 4, 0); 
IF < THEN QUITPROG (14); 
END. 
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$CONTROL USLINIT 

<< Purpose: >> •■%.-* 

« Receive data from other process and print it. ^> 

BE6IN 

LOGICAL EOF := FALSE; 

INTEGER LEN, IN'FILE, OUT'FILE; 

BYTE ARRAY IN'FILE'NAME (0:8) := "MSGFILE2 "; 
BYTE ARRAY OUT * FILE ' NAME (0:8) := "MS6FILE1 "; 
ARRAY MESSAGE (0:39); 

INTRINSIC FCLOSE, FOPEN, FREAD, FWRITE, QUITPROG, PRINT; 
<< Open message file for traffic from other process: >> 

<< Note that IN'FILE'NAME ("MSGFILE2") is opened with FOPTIONs 

<< %106 and AOPTIONs %1 1 00: %106 indicates an old temporary 

<< ASCII file and %1100 indicates a reader process with 

<< exclusive access and multiaccess capability. MSGFILE2 

<< has already been designated as a message file. Since 

<< only one reader and one writer process will be accessing 

<< the message file, exclusive access 



mode i s soeci f i ed. 



IN'FILE := FOPEN (IN'FILE'NAME, %106, %1100); 
IF < THEN QUITPROG (13); 



<< Open 



message file for traffic to other process: 



>> 



<< 
<< 
<< 
<< 
<< 
<< 
<< 



Note 
%106 



that OUT'FILE'NAME ("MSGFILE1") is opened with FOPTIONs 
and AOPTIONs %1 1 01 : X106 indicates an old temporary 
ASCII file and %1 1 01 indicates a writer process with 
exclusive access and multiaccess capability. MSGFILE1 
has already been designated as a message file. Since only 
one reader and one writer process will be accessing the 
file, exclusive access mode is specified. 



message 

OUT'FILE := FOPEN (OUT'FILE'NAME, %106, %1101); 
IF < THEN QUITPROG (14); 

WHILE NOT EOF DO BEGIN 

LEN := FREAD (IN'FILE, MESSAGE, -80); 

IF < THEN QUITPROG (15); 

IF > THEN EOF := TRUE 

ELSE PRINT (MESSAGE, -LEN, 0); 
END << WHILE >>; 

<< Now signal other process; we are done. >> 

FCLOSE (OUT'FILE, 4, 0); 
IF < THEN QUITPROG (16); 

FCLOSE (IN'FILE, 4, 0); 
IF < THEN QUITPROG (17); 



>> 
>> 
>> 
>> 
>> 
>> 
>> 



>> 
>> 
>> 
>> 
>> 
>> 
>> 



END 
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These two COBOL programs perform the same tasks as the preceding SPL programs: the first pro- 
gram, FATHERPROC, reads data from a data file and wrties it to MSGFILE2; the second program, 
SONPROC, can then read this data from MSGFILE2 and print it. When SONPROC finishes reading 
and printing the data, it writes a message to MSGFILE1 indicating this and terminates. FATHER- 
PROC reads this message from MSGFILE1 and also terminates. The messages travel among processes 
and message files as illustrated in Figure 3-2: 
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Figure 3-2. Data paths among processes and message files. 
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* ERROR VARIABLES 
01 ERROR-BUFFER. 

05 FILLER PIC X OCCURS 1 TO 80 TIMES 
DEPENDING ON LEN. 
01 ERR-NUM PIC S9C4) COMP. 
01 FILE-NUM PIC S9C4) COMP. 
01 QUIT-PARM PIC S9C4) COMP. 
PROCEDURE DIVISION. 
MAIN PROCESSING SECTION. 

SDEFINE %QUITPROG= 

MOVE 11 TO QUIT-PARM 

MOVE !2 TO FILE-NUM 

PERFORM PRINT-ERRORS 
DRIVER-PARA. 

PERFORM INIT-PARA. 
MOVE "F" TO EOF-VAR. 
PERFORM LOAD-PARA UNTIL EOF. 
PERFORM CLOSE-PARA. 
STOP RUN. 

* Create entries for the message files in the directory. 



QUITPROG 
QUITPROG 
QUITPROG 
QUITPROG 



* Note that IN-FILE-NAME C "MSGF ILE1 ") is opened with FOPTIONs 

* %30004: this indicates a new ASCII message file. 
* 

INIT-PARA. 

CALL INTRINSIC "FOPEN" 

USING IN-FILE-NAME %30004 
GIVING IN-FILE. 

IF CC NOT = 

%QUITPROG(1#,IN-FILE#) . 
CALL INTRINSIC "FCLOSE" USING IN-FILE %2 %0. 

IF CC NOT = 

%QUITPR0G(2#,IN-FILE#). 

* Note that OUT-FILE-NAME ( "MSGF ILE2") is opened with FOPTIONs 

* %30004: this indicates a new ASCII message file. 
* 

CALL INTRINSIC "FOPEN" 

USING OUT-FILE-NAME %30004 
GIVING OUT-FILE. 

IF CC NOT = 

%QUITPR0G(3#,0UT-FILE#). 
CALL INTRINSIC "FCLOSE" USING OUT-FILE %2 %0. 

IF CC NOT = 

•/.QUITPROG (4#, OUT- F I LE#). 

* 

* Create and activate the print process. 

CALL INTRINSIC "CREATEPROCESS" USING \ PIN PRINTPROC. 

IF CC NOT = 

%QUITPROG(5#,-1#) . 
* 
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* 
* 
* 
* 
* 
* 
* 
* 
* 
* 



* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 



* 
* 
* 
* 
* 
* 
* 
* 



* 
* 
* 



and 



Open message file for traffic from print process. 

Note that IN-FILE-NAME ( "MSGFI LE1 ") is opened with FOPTIONs 
%106 and AOPTIONs %1100: %106 indicates an old temporary 
ASCII file and %1100 indicates a reader process with exclu- 
sive access and multiaccess capability. MSGFILE1 has already 
been designated as a message file. Since only one reader 
one writer process will be accessing the message file, 
exclusive access mode is specified. 

CALL INTRINSIC "FOPEN" 

USING IN-FILE-NAME %106 %1100 

GIVING IN-FILE. 
IF CC NOT = 

%QUITPR0G (7#,IN-FILE#). 

Open message fiLe for traffic to print process. 



Note 
%106 



that OUT-FILE-NAME 
and AOPTIONs %11Q1; 



("MSGFILE2") is opened with FOPTIONs 
%106 indicates an old temporary 
%1101 indicates a writer process with exclu- 
sive access and multiaccess capability. MSGFILE2 has already 
been designated as a message file. Since only one reader 
process will be accessing the message file, 
mode i s spec i f i ed. 



ASCII file and 



one writer 
exclusive access 



and 



CALL INTRINSIC "FOPEN" 

USING OUT-FILE-NAME %106 %1101 

GIVING OUT-FILE. 
IF CC NOT = 

%QUITPR0G(8#, 0UT-FILE#). 



Open data input file. 

Note that DATA- FILE-NAME ("DATA") is 
and AOPTIONs 0: %3 indicates an old 
file and indicates read only 
change the FOPTIONs to specify 



opened with FOPTIONs %3 
permanent or temporary 

access. The file system will 

an ASCII file. 



CALL INTRINSIC "FOPEN" 

USING DATA-FILE-NAME %3 %0 

GIVING DATA-FILE. 
IF CC NOT = 

%QUITPR0G(9#,DATA-FILE#). 
Load input to message file. 
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LOAD-PARA. 

CALL INTRINSIC "FREAD" 

USING DATA-FILE MESSAGE-BUF -80 
GIVING LEN. 
IF CC NOT = 

IF CC LESS THAN THEN 

%QUITPR0G(10#,DATA-FILE#) 

ELSE 

MOVE "E" TO EOF-VAR 

ELSE 

COMPUTE LEN = - LEN 
CALL INTRINSIC "FWRITE" 

USING OUT-FILE MESSAGE-BUF LEN %0 

IF CC NOT = 

%QUITPR0G(11#,0UT-FILE#). 

r \ o^f~PARA 

CALL INTRINSIC "FCLOSE" USING OUT-FILE %4 %0. 

IF CC NOT = 

%QUITPR0G(12#,0UT-FILE#). 

* 

* Wait for print to finish. 

CALL INTRINSIC "I-REhu uSinu j." ■ .■.•-- ■■- u - D - 

IF CC < 

%QUITPROG(13#,IN-FILE#). 
CALL INTRINSIC "FCLOSE" USING IN-FILE %4 %0. 

IF CC NOT = 

%QUITPROG(14#,IN-FILE#). 

* 

* General error routine. 
* 

PRINT-ERROR SECTION. 
WHAT-TYPE. 

IF FILE-NUM IS NOT NEGATIVE THEN 

CALL INTRINSIC "FCHECK" USING FILE-NUM ERR-NUM 

CALL INTRINSIC "FERRMSG" USING ERR-NUM ERROR-BUFFER LEN 

«. i- « r* i aw r-nnnD_DIICCCD 
DliTLHI LR^uix u»«j i i i- ■* - 

IF QUIT-PARM IS NOT NEGATIVE THEN 

CALL INTRINSIC "QUITPROG" USING QUIT-PARM. 



SCONTROL USLINIT 
IDENTIFICATION DIVISION. 
PROGRAM-ID. SONPROC. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. HP3000. 
OBJECT-COMPUTER. HP3000. 
SPECIAL-NAMES. 
CONDITION-CODE IS CC. 
DATA DIVISION. 
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WORKING-STORAGE SECTION. 



01 LEN 

01 IN-FILE 

01 OUT-FILE 

01 IN-FILE-NAME 

01 OUT-FILE-NAME 

01 MESSAGE-BUF 

01 EOF-VAR 
88 EOF 

* Error variables 
01 ERROR-BUFFER. 
05 FILLER 



PIC S9C4) COMP. 

PIC S9(4) COMP. 

PIC S9(4) COMP. 

PIC X(9) VALUE "MSGFILE2 

PIC X(9) VALUE "MSGFILE1 

PIC X(80). 

PIC X. 

VALUE "E". 



PIC X OCCURS 

DEPENDING 

PIC S9(4) 

PIC S9(4) 

PIC S9(4) 



01 ERR-NUM 

01 FILE-NUM 

01 QUIT-PARM 

PROCEDURE DIVISION. 

MAIN-PROCESSING SECTION. 
$DEFINE %QUITPROG= 

MOVE M TO QUIT-PARM 
MOVE !2 TO FILE-NUM 
PERFORM PRINT-ERROR# 

DRIVER-PARA. 

PERFORM OPEN-PARA. 
MOVE "F" TO EOF-VAR. 
PERFORM READ-PARA UNTIL 
PERFORM CLOSE-PARA. 
STOP RUN. 



1 TO 
ON LEN. 
COMP. 
COMP. 
COMP. 



80 TIMES 



QUITPROG 
QUITPROG 
QUITPROG 
QUITPROG 



EOF. 



* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 



Open message file for traffic from other process. 

Note that IN-FILE-NAME ("HSGFILE2") is opened with FOPTIONs 
%106 and AOPTIONs %1100: %106 indicates an old temporary 
ASCII file and %1100 indicates a reader process with 
exclusive access and multiaccess capability. MSGFILE2 has 
already been designated as a message file. Since only one 
reader and one writer process will be accessing the 
file, exclusive access mode is specified. 



message 



* 
* 
* 
* 
* 
* 
* 



OPEN-PARA. 

CALL INTRINSIC "FOPEN" 

USING IN-FILE-NAME %106 %1100 
GIVING IN-FILE. 
IF CC NOT = 

%QUITPR0GC15#,IN-FILE#). 

Open message file for traffic to other 



process . 

Note that OUT-FILE-NAME ("MSGFILE1") is opened with FOPTIONs 
%106 and AOPTIONs %1 1 01 : %106 indicates an old temporary 
ASCII file and %1101 indicates a writer process with exclu- 
sive access and multiaccess capability. MSGFILE1 has already 



3-20 



* been designated as a message file. Since only one reader and 

* one writer process wi L L be accessing the message file, 

* exclusive access mode is specified. 
* 

CALL INTRINSIC "FOPEN" 

USING OUT-FILE-NAME %106 %1101 
GIVING OUT-FILE. 

IF CC NOT = 

%QUITPR0G(16#,0UT-FILE#) . 

* 

* Read messages from message file. 
* 

READ-PARA. 

CALL INTRINSIC "FREAD" 

USING IN-FILE MESSAGE-BUF -80 
GIVING LEN. 
IF CC NOT = 

IF CC LESS THAN THEN 

%QUITPR0G(17#,IN-FILE#) 

ELSE 

MOVE "E" TO EOF-VAR 
* 

** ri l l l i. mCsalj^*. w >- - - 
* 

ELSE 

COMPUTE LEN = - LEN 
CALL INTRINSIC "PRINT" 

USING MESSAGE-BUF LEN %0 
IF CC NOT = 

%QUITPR0G(18#,2#) . 

* 

* Now signal the other process; we are done. 
* 

r \ n*^F — PARA 

CALL INTRINSIC "FCLOSE" USING OUT-FILE %4 %0 . 

IF CC NOT = 

%QUITPR0G(19#,0UT-FILE#). 
CALL INTRINSIC "FCLOSE" USING IN-FILE %4 %0 . 
tf rr not = 

%QUITPR0G(20#, IN- FILES). 

* 

* General error routine. 
* 

PRINT-ERROR SECTION. 
WHAT-TYPE. 

IF FILE-NUM IS NOT NEGATIVE THEN 

CALL INTRINSIC "FCHECK" USING FILE-NUM ERR-NUM 

MOVE 80 TO LEN 

CALL INTRINSIC "FERRMSG" USING ERR-NUM ERROR-BUFFER LEN 

DISPLAY ERROR-BUFFER. 

._ ~..-r->- nnr.ua TC MOT MCCJTTUC THFM 
il- UUJ.I - r«Bn iO IIUI mi. wr. I .. . - ■•• 

CALL INTRINSIC "QUITPROG" USING QUIT-PARM. 
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UTILITY FUNCTIONS OF 
WIPE INTRINSICS 



SECTION 



IV 



MPE intrinsics allow you to perform the following utility functions: 

• Manage library procedures with LOADPROC (see page 4-2) and UNLOADPROC (see page 4-3). 

• Convert numbers from ASCII to binary code with BINARY and DBINARY. See page 4-13. 

• Convert numbers from binary to ASCII code with ASCII and DASCII. See page 4-10. 

• Convert a string of characters from EBCDIC to ASCII, from ASCII to EBCDIC, from EBCDIC to 
JIK (Katakana), and from JIK to EBCDIC with CTRANSLATE. (See page 4-13). 

• Read input from job/session list devices with READ and READX. See page 4-16. 

• Write output to the job/session list device with PRINT. See page 4-18. 

• Write output to the Operator's Console with PRINTOP or write output to the Operator's Console 
and solicit a reply with PRINTOPREPLY. See page 4-18. 

• Obtain system timer information with TIMER. See page 4-42. 

• Obtain the calendar date with CALENDAR. See page 4-44. 

• Obtain the time of day in terms of hour, minute, second, and tenth of second with CLOCK. See 
page 4-44. 

• Format the calendar date with FMTCALENDAR. See page 4-45. 

• Format the time of day with FMTCLOCK. See page 4-45. 

« Format the calendar date and time of day with FMTDATE. See page 4-45. 

• Obtain process run time (CPU time) with PROCTIME. See page 4-44. 

• Obtain information pertaining to your access mode and attributes with WHO. See page 4-10. 

• Search an array for a specified name with SEARCH. See page 4-3. 

• Format the parameters of a non-MPE command with MYCOMMAND. See page 4-4. 

• Execute MPE commands programmatically with COMMAND. See page 4-9. 

• Enable or disable hardware arithmetic traps with ARITRAP. See page 4-30. 

• Enable or disable software arithmetic traps with XARITRAP. See page 4-32. 

• Enable or disable the software library trap with XLIBTRAP. See page 4-34. 

• Enable or disable the software system trap with XSYSTRAP. See page 4 - 36 . 

• Disarm the CONTROL-Y trap with RESETCONTROL (see page 4-40) or arm the CONTROL-Y 
trap with XCONTRAP (see page 4-41). 

• Change the size of the current DL-to-DB area with DLSIZE. See page 4-22. 

• Change the size of the current Z-to-DB area with ZSIZE. See page 4-27. 

• Suspend the calling process with PAUSE. See page 4-19. 

• Tnitiafo n sosainn hrpak nrnfframmaticallv with CAUSEBREAK. See page 4-19. 

• Programmatically terminate a process (after successful execution) with TERMINATE. See 
page 4-20. 

• Programmatically abort any process within a user process structure with QUIT. See page 4-20. 

, .. i... _j a. / \ :au r\r tttvtjt) r\r^ a^s* ^nw. A on 

• ADOn tne entire process Structure (prugreuuj wim njum xt\_»>j. ucc j-'c.ftc -x-<jv. 

• Manage interprocess communication through the job control words with SETJCW (see page 4-46), 
GETJCW (see page 4-46), PUTJCW (see page 4-47), and FINDJCW (see page 4-47). 

• Access a message catalog in the MPE message system, and insert parameters in a message, with the 
GENMESSAGE intrinsic. See page 4-50. 

• Control function of 2680 A page printer. ■ 
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DYNAMIC LOADING AND UNLOADING OF LIBRARY PROCEDURES 

Normally, segments containing library procedures referenced by a program are attached to that 
program when the program is allocated in virtual memory. However, you also may dynamically 
attach and detach such procedures while your program is running. You might, for example, decide 
to do this for a large procedure used optionally and infrequently by your program, or for a procedure 
whose name is not known at load time. By loading this procedure only when it is required, and then 
unloading it, you can save the table entry. The procedures are loaded from segmented libraries, not 
from relocatable libraries (which are used only at program-preparation time). 

NOTE 

Preparation and maintenance of segmented libraries and 
relocatable libraries is explained in the Segmenter Reference 

Manual. 

You need not load procedures dynamically that are declared as externals to your program, because 
the loader will load them automatically. Dynamic loading and unloading is intended for procedures 
that are not declared at all. 

DYNAMIC LOADING 

The LOADPROC intrinsic is used to load a library procedure, together with external procedures 
referenced by it. 

For example, to dynamically load a procedure named PROC1, you could enter the following 
intrinsic call: 

PNUM : =LO ADPROC(PNAME,0,L AB) ; 

The parameters specified in the above intrinsic call are 

procname Contained in the byte array PNAME. The contents of PNAME are 

"PROC1". Note that the last character is a blank. 

Mb 0, signifying that only the system library should be searched. 

If 2 were specified, library searching would proceed in this order: 

Group Library 

Account Public Library 

System Library 
Specifying 1 for the lib parameter would cause the search to be 
conducted in this order: 

Account Public Library 

System Library 

plabel LAB, a word to which the procedure's label (P label) is returned. 

When the LOADPROC intrinsic executes, the procedure identity number will be returned as an 
integer to PNUM. 
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Example 2 : 

BYTE ARRAY SHORTCOMMANDS (0:29) : = 

Entry Definition 

6,1,'T\ "INa ", 

7,l',"0''\ "OUT a ", 

g'v'S",' "SKIPa ", 

8',l!"E"' "EXITa ", 
0; 

NOTE : This would enable the program to allow abbreviations and replace them with the full 
command. 

Example 3 : 

BYTE ARRAY RESPONSET ABLE (0:9): = 

5,3,"YES", 

4,2,"NO", 

0; 

NOTE: In this example, the definition portion was not deemed necessary by the main program. 

You can request the search of such an array for a specified name with the SEARCH intrinsic. A 
simple linear search is performed, with the name, specified as a byte array, compared against the 
byte array forming the name in each entry. Because the search is linear, the most frequently used 
byte arrays should appear at the beginning of the array to promote efficient searching. If the name 
is found, the number of the entry containing the name is returned to the calling program. If the 
name is not found, a zero is returned. Optionally, you also can request the return of a pointer to the 
definition information for the name. 

If you want to search the byte array in Example 1 for the string "IN", the following intrinsic call 
could be used. 

BYTE ARRAY COMMAND (0:3);MOVE COMMAND ;= "IN"; 
ENUM: = SEARCH (COMMAND ,2,COMMANDTABLE JDEFADDR ) ; 

The length of the string in COMMAND is 2 bytes. The byte address of the definition sought is to be 
returned to the word DEFADDR. The entry number corresponding to the entry containing "IN" 
will be returned to the word ENUM. 
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DYNAMIC UNLOADING 

The UNLOADPROC intrinsic is used to unload a procedure and its referenced external procedures. 

For example, to unload the procedure that was dynamically loaded in the previous example, you 
could use the following UNLOADPROC intrinsic call: 

UNLOADPROC(PNUM) ; 

SEARCHING ARRAYS 

Occasionally, you may construct byte arrays whose contents you may later want to search for 
specified entries or names. A dictionary of user-designed commands is one such example. The 
searching is accomplished with the SEARCH intrinsic, which can be used with specially-formatted 
arrays consisting of sequential entries, each including: 

• An integer specifying the length (in bytes) of the entire entry - the length includes this 
byte plus all the information in the following byte areas. 

• An integer specifying the length of the "name" (in bytes) for which the search is 
performed. 

• A byte string forming the name for which the search is performed - in a command 
dictionary, for example, this would be the command name. 
An optional byte string containing a user-supplied definition. 
A zero, as the length of the last entry, indicating the end of the dictionary. I 






The entry number of the first entry in such a dictionary is one, If the entry is not found, it is indi- 
cated by a zero. 

In the following examples, consider a byte array wherein the relationship of each entry to its 
definition is: 

Example 1 : 

BYTE ARRAY COMMANDTABLE(0:25): = 

Entry Definition 

5, 2, "IN", 1, 

6,3,"OUT", 1, 

7,4 ; "SKIP", 2, 

7,4,"EXIT", 0, 
0; 

NOTE : The main program presumably will use the definitions to mean: 

= No parameter follows 

1 = Filename parameter follows 

2 = Numeric parameter follows 



I 
i 
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FORMATTING COMMAND PARAMETERS 

You can programmatically extract and format for execution the parameters of a command defined 
by you (i.e., the command is not an MPE command) with the MYCOMMAND intrinsic. 
Additionally, you can have the MYCOMMAND intrinsic search a byte array for the specified 
command. 

Figure 4-1 contains a program that checks if the user is running the program in a session and, if such 
is the case, performs the following: 

1. Prompts the user to enter a command name from the terminal. 

2. Reads the command name typed in by the user. 

3. Compares this command name against entries in a byte array. If no match is found, the 
program displays 

ILLEGAL ENTRY 
and prompts the user for another command. 

4. Converts the parameter, entered with the command, to binary, then uses this operand to 
perform the calculation specified by the command. 

5. Converts the result to ASCII, then displays the result on the terminal. 

The statement 

LGTH:=READ(INPUT,-72); 

reads the command entered by the user (the arrays INPUT and COMMAND have been equivalenced, 
see statement 6 in the program). 

The two statements 

IFOTHENQUIT(l); 

IF COMMAND = "END" THEN GO EXIT; 

perform the following: 

1. Check for a condition code error and execute the QUIT intrinsic (causing the process to 
abort if a condition code error is returned). 

2. Cause program control to transfer to the statement EXIT if "END" is entered by the 
user. 

The statement 

COMMAND(LGTH):=%15; 

adds a carriage-return character as the last character of the comimage parameter for the command 
entered. Note that the carriage-return character is added starting at the position in the array 
specified by LGTH, but does not overwrite the last position of the string entered by the user. The 
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00001000 

00002000 

00003000 

00004000 

00005000 

00006000 

00007000 

00008000 

00009000 

00010000 

00010100 

00011000 

00012000 

00013000 

00014000 

00015000 

00016000 

00017000 

00019000 

000200JO 

00021000 

00022000 

00023000 

00024000 

00025000 

00026000 

00027000 

00028000 

00028100 

00029000 

00030000 

00031000 

00032000 

00033000 

00034000 

00035000 

00036000 

00036100 

00037000 

00038000 

00039000 

00040000 

00041000 

00042000 

00043000 

00044000 

00045000 

00046000 

00047000 

00048000 

00049000 

00050000 

00051000 

00052000 

00053000 

00054000 



00000 
00000 



ooono l 



00011 
00007 
00007 



00007 1 
00010 1 
00010 1 
00001 1 
00010 1 
00016 1 
00016 1 
00016 1 
00016 1 
00016 1 
00016 1 
00016 1 
00016 1 
00016 1 
00016 1 



00004 
00010 
00010 



00016 1 
00023 1 
00026 1 
00040 1 
00043 1 
00043 1 
00050 1 



00056 1 

00057 1 
00062 1 
00065 1 
00070 1 

00075 1 

00076 1 
00076 1 
00100 1 
00106 2 
00116 2 
00122 2 
00126 2 
i 3 j 2 
00136 7 
00143 1 
00143 1 
00155 1 
00163 1 

00170 1 

00171 1 
00171 1 
00175 1 

00201 1 

00202 1 



SCONTPOL USLINIT 
BEGIN 

ARRAY HEADING(0:8):="INTEGFR CALCULATOR"; 

ARRAY ERRMSG(0:6):="ILLEGAL ENTRY. "; 

ARRAY INPUT(0:36); 

BYTE ARRAY COMMANDC*) =INPUT; 

BYTE ARRAY ANSWERCO ! 1 3 ) : =" ACCUM = "; 

ARRAY OUTPUT(«)=ANSWEP; 

BYTE ARRAY TABLEC : 25) : = 

5, 3, "ADD", 5, 3, "SUB", 5,3,"MUL", 
5,3,"DIV", 5, 3, "SET", 0; 

INTEGER ARRAY PARMINFOCO : 1) ; 

LOGICAL INTEPACTIVE:=FALSE; 

INTEGER ACCUM:=0, OPERAND:=0, REG:="? ", 

LGTH, INDX, PARMCNT, TYPE; 

INTRINSIC ASC1I,BINARY,READ,PRINT,MYCOMMAND,QUIT,V.HO; 



«END OF DECLAPATIONS>> 



LOOP: 



PRINT(HEAPING,9,0); 
WHOCINTERACTIVE); 

IF INTERACTIVE THEN PRINT fPEQ, 1 , %320) 

ir ,-tws«e>3,- |j r.w not m 5 "x;?» 

C'}>'*tAfc')i L-C-i -i 1 t fi%3 b 7 

Tl r? ; =H Y Cf1«MA-i'-! I r'.iMMftS U , , 1 , F A h"*.'.* ' - 
PAR11 vfr.jTAaLE:; 

if < TtfEs On t,m^i 

- : - fi'.vr-HTKit Tv -f»; r** Ftoni;. 

rAPMlNrfiri ■,C0:C , 3; 

If <V THE'. <& rl^PO-j 

CASE tTYPr-t) Of 
BEGtS 

sct»,« : = Acm >«*n Hh a A "P ! 
ACC'i " I **C. ■"< . OPC* A <8E : 



RESULT: 



ERROR: 



exit: 

E=%020; 



PRIMARY DB STORAG 
NO. ERPORS=000; 
PROCESSOR TIME=0:00:03; 



MOVE ANSWERC8):=" "! 
ASCII (ACCUM, 10. ANSWER C 8)); 
PRINT(OUTPUT,7,0)S 
GO LOOP; 

PRINT(ERRMSG,7,0) : 

IF NOT INTERACTIVE THEN GUITC2); 
GO LOOP; 
END. 

SECONDARY DB STORAGE=%001 1 3 
NO. WARNINGS=000 
ELAPSED TIME=0:00:11 



«PROGRAM ID>> 
<<LIVE USER?>> 

<<PROMPT USER>> 
«GET CGbS«I,H£v> 
t<CHI;CK FCte F.RRt>R» 

iiiiii - liiiii 

«TAK£ APAPT CO»«J*KD» 

«*!*0 Cft«'HA«r «fATCH» 
<<HO S>AftftWET£8S» 
«5tJ|iSCRIPT «r PARtf» 
«CO«fVlift1 fSSAWre Ki> 

«CH£CK FOR £JWJ*» 

«<&£LECT OP£!RATTW» 
«AtH> C£i-4MA«P» 

«sir» cnf*SAH5»> 

<<i>iv cn«t»ftMt>» 

iisil t"o*?MA«r»> 



<<RESET OLD ANSWER» 
<<CONVERT ACCUM>> 
«OUTPUT NEW ANSWER>> 
<<C0NTINUE CALCULATIONS 

<<ERROR MESSAGE>> 
<<NO LIVE USER-QUIT>> 
«CONTINUE CALCULATIONS 



Figure 4-1. Using the MYCOMMAND Intrinsic 
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reason for this is that, in SPL convention, the first position in an array is 0, not 1. For example, if 
the user entered the command ADD 5, this command would occupy array positions through 4, as 
follows: 




A 



1 
D 



2 
D 



4 
5 



The value returned to LGTH specifying the length of the string read, however, is 5 because the 
READ statement read a string 5 characters long and therefore the carriage-return character is added 
to position 5 of the array. 

The statement 

TYPE:=MYCOMMAND(COMMAND„l,PARMCNT,PARMINFO,TABLE); 

calls the MYCOMMAND intrinsic to parse the command entered by the user. The parameters 
specified are 



comimage 



Contained in the array COMMAND, which contains the string entered 
by the user. This parameter contains a user command such as ADD or 
SUB, a parameter consisting of an integer, and a carriage-return 
character added to the command by the statement 



COMM AND(LGTH) : =%1 5 ; 

For example, the complete comimage parameter could be ADD 15%15, 
with ADD 15 entered by the user and the %15 carriage return added 
programmatically. 



delimiters 



Omitted. The default delimiter array "comma, equal, semicolon, 
carriage return" is used. 



maxparms 
numparms 



1, specifying that one parameter is expected in comimage. 

Specified by PARMCNT, which contains the actual number of param- 
eters entered with the command. 



parms 



Specified by PARMINFO, an integer array to which is returned the 
byte address of the parameter entered as part of comimage. 



NOTE 

Although this parameter is listed as a double array in the 
specifications for the MYCOMMAND intrinsic in Section II, 
it is declared as a two-word integer array in this program 
because it is necessary to access each of the words indivi- 
dually. This is more convenient than declaring a one-word 
double array and a two-word integer array, then 
equivalencing the two. 
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diet 



Specified by TABLE, a byte array containing 5,3,"ADD", 5,3,"SUB", 
5,3,"MUL", 5,3,"DIV", 5,3,"SET", 0; 



The table specified by the diet parameter is searched until a match is found between the command 
name and an entry in the table. If a match is found, the number of the entry in the table containing 
the matching name is returned to TYPE. The diet parameter specifies a specially-formatted array, or 
table. Each entry in the table contains: 

1. An integer specifying the total number of bytes in the entry. 

2. An integer specifying the total number of characters in the command portion of the 
entry. 

3. The command portion of the entry. 

4. An arbitrary user-defined definition of the entry. 

For example, the first entry in the array TABLE is 

5,3,ADD 
which is broken down as follows: 

5 The total number of bytes in this entry (53ADD = 5 bytes). 
3 The total number of bytes in the command portion (ADD) of the entry. 
ADD The string comprising the command portion of the entry. 

Note that a user-defined definition of the entry is not included in the entries in TABLE. 

The byte array TABLE, then, consists of 26 bytes structured as follows: 



5 


3 


A 


D 


D 


5 


3 


S 


U 


B 


5 


O 


M 


U 


L 


5 


3 


D 


I 


V 


5 


3 


S 


E 


T 
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The statement 

IF < THEN GO ERROR; 
checks the condition code and, if it is CCL, transfers program control to statement label ERROR. 
The statement 

IF PARMCNT < > 1 THEN GO ERROR; 

checks that only one parameter was entered with the command (the parameter maxparms had 
specified that one parameter was expected). If PARMCNT does not equal 1, control is transferred 
to statement label ERROR. 

The two statements 

INDX :=PARMINFO-@COMM AND; 
OPERAND:=BINARY(COMMAND(INDX),PARMINFO(1).(0:8)); 

determine the byte address of the parameter entered with the command, then convert this parameter 
to a binary value. 

The first statement above 

INDX:=PARMINFO-@COMMAND; 

subtracts the byte address of the first element of COMMAND from the byte address of PARMINFO 
to obtain the relative position of the parameter in the array COMMAND. This value is returned to 
INDX. For example, the command 

ADD 5 

would occupy positions in the array COMMAND as follows: 

12 3 4 
ADD 5 

Subtracting the byte address of the first (zero) element of COMMAND from the byte address 
specified by PARMINFO for the first element of the parameter produces the byte address of the 
parameter. 

The statement 

OPERAND:=BINARY(COMMAND(INDX),PARMINFO(1).(0:8)); 

converts the ASCII characters starting in the INDX position of the array COMMAND to a binary 
value and returns this value to OPERAND. The number of bytes (length) of the ASCII string to be 
converted are specified by the first eight bits (PARMINFO(1).(0:8)) of the first word contained in 
PARMINFO 
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The statement 

CASE (TYPE-1) OF 

transfers orogram control to one of the five statements following the BEGIN statement, depending 
on the value of TYPE-1. Note that -1 is necessary because the five statements are considered in the 
SPL numbering convention by the CASE statement (ACCUM :=ACCUM+OPER AND; is considered 
to be the zeroth statement following BEGIN) but the value assigned to TYPE by MYCOMMAND 
contains the range 1 to 5. 

An example of running the program is shown below. 

; RTJN UTILY 

INTEGER CALCULATOR 

? SET 10 

AC CUM = 10 

? ADD 34 

ACCUM = 44 

? MTjL . 5 

ILLEGAL ENTRY 

? MUL S 

ACCUM =88 

? END 

END OF PROGRAM 



EXECUTING MPE COMMANDS PROGRAMMATICALLY 

The COMMAND intrinsic can be used to programmaticaUy request the execution of certain MPE 
commands. The command image, including parameters, is passed to the intrinsic, which searches the 
system command dictionary for a command of the same name, and executes it. When command 
execution is completed, or when an error is detected during this execution, control returns to the 
calling process. Commands that can be executed programmatically are listed below. 



ABORTIO 

ABORTJOB 

ACCEPT 

ALLOW 

ALTACCT 

ALTGROUP 

ALTJOB 

ALTLOG 

ALTSEC 

ALTSPOOLFILE 

ALTUSER 

ALTVSET 

ASSOCIATE 

BREAKJOB 

BUILD 



COMMENT 

r^rMVTO/^T XT 

DEALLOCATE 

DELETESPOOLFILE 

DISALLOW 

DISASSOCIATE 

DOWN 

DOWNLOAD 

DSCONTROL 

DSLINE 

DSTAT 

FILE 

FOREIGN 

GETLOG 

GETRIN 



GIVE 

HEADOFF 

HEADON 

HELP 

IMLCONTROL 

JOBPRI 

JOBSECURITY 

LDISMOUNT 

LIMIT 

LISTACCT 

LISTF 

LISTGROUP 

LISTLOG 

LISTUSER 
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LISTVS 

LMOUNT 

LOG 

MPLINE 

MRJECONTROL 

NEWACCT 

NEWGROUP 

NEWUSER 

NEWVSET 

OUTFENCE 

PTAPE 

PURGE 

PURGEACCT 

PURGEGROUP 

PURGEUSER 

PURGEVSET 

RECALL 

REFUSE 

RELEASE 

RELLOG 

REMOTE 

REMOTE HELLO 



RENAME 

REPLY 

REPORT 

RESET 

RESETACCT 

RESETDUMP 

RESTORE 

RESUMEJOB 

RESUMELOG 

RESUMESPOOL 

SAVE 

SECURE 

SETDUMP 

SETJCW 

SETMSG 

SHOWALLOW 

SHOWCOM 

SHOWDEV 

SHOWIN 

SHOWJCW 

SHOWJOB 

SHOWLOG 



SHOWME 

SHOWOUT 

SHOWQ 

SHOWTIME 

SPEED 

STARTSPOOL 

STOPSPOOL 

STORE 

STREAM 

STREAMS 

SUSPENDSPOOL 

SWITCHLOG 

TAKE 

TELL 

TELLOP 

TUNE 

UP 

VMOUNT 

WARN 

WELCOME 



See the MPE Commands Reference Manual and the Console Operator's Guide for discussions of 
commands. 

If you want to programmatically execute the command : SHOWTIME, the following intrinsic call 
could be used: 

COMMAND(COMD,ECODE,EPARM); 

All characters for the command except the prompting colon are contained in the byte array COMD. 
Any error code is returned to ECODE. Since the : SHOWTIME command has no parameters, no 
information is returned to EPARM. 

When the intrinsic executes, the date and time are printed on the job/session list device. 

NOTE 

Conditions which result in warning messages are not returned 
to the user. 

DETERMINING THE USER'S ACCESS MODE AND ATTRIBUTES 

A program can obtain the access mode and attributes of the user running that program from the 
system tables with the WHO intrinsic. 

Figure 4-2 contains a program which must determine if the user is running the program in an 
interactive session. The statement 

WHO(INTERACTIVE); 
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00001000 00000 
00002000 00000 
00003000 00000 1 
00004000 00011 1 
00005000 00007 1 
00006000 00007 1 
00007000 00007 1 
00008000 00010 1 
00009000 00010 1 
00010000 00001 1 
00010100 00010 1 
00011000 00016 1 
00012000 00016 1 
00013000 00016 1 
00014000 00016 1 
00015000 00016 1 
00016000 00016 1 
00017000 00016 1 
00019000 00016 1 
00020000 00016 1 
00021000 00016 1 
00022000 00004 1 
00023000 00010 1 
00024000 00010 1 
00025000 00016 1 
00026000 00023 1 
00027000 00026 I 
00028000 00040 1 
00028100 00043 1 
00029000 00043 1 
00030000 00050 1 
00031000 00056 1 
00032000 00057 1 
00033000 00062 1 
00034000 00065 1 
00035000 00070 1 
00036000 00075 1 
00036100 00076 1 
00037000 00076 1 
00038000 00100 1 
00039000 00106 2 
00040000 00116 2 
00041000 00122 2 
00042000 00126 2 
00043000 0013? 2 
00044000 00136 7 
00045000 00143 1 
00046000 00143 
00047000 00155 
nnriiiQnriQ 00163 
00049000 00170 
00050000 00171 
00051000 00171 
00052000 00175 
00053000 00201 
00054000 00202 
PRIMARY DB STO 
NO. ERROPS=000 
PROCESSOR TIME 



SCONTPCL USLINIT 

ARRAY HEADINGC0:8):="INTEGER CALCULATOR"? 

ARRAY FPPMSG(0:6):= n ILLECAL ENTRY."; 

ARRAY INPUT(0:36) ; 

BYTE ARRAY COMMANDC*)=INPUT; 

BYTF ARRAY ANSWERCO : 1 3 ) :=" ACCUM = "; 

ARRAY OUTPUT(»)=ANSWEPj 

BYTE ARRAY TABLEC ! 25 ) : = 

5, 3, "ADD", 5, 3, "SUB", 5,3,"MUL 
5.3,"DIV", 5, 3, "SET", 0; 

INTEGER ARRAY PARMINFO( : 1 ) I 

LOGICAL INTERACTIVE:=FALSE; 

INTEGER ACCUM:=0, GPERAND:=0, PE0:="? ", 
L GTH, INDX, PARMCNT, 

INTRINSIC ASCI I, BINARY, READ, PRINT, MYCOMMAND 
<<END OF DECLAPATIONS>> 



TYPE? 

,QUIT,VsHO; 



lllill 



PHINT(HEADING,9,0): 

WHO! UsTePftCi) *x ' 

Ir INTERACTS THEN PRINTf BEO, 1 ,%320) J 
"lGTH ! = REAO ( INPUT, -72 ) J 
IF <> THEM QUITC1) ! 
IF COKMAND="END" THEN GO EXIT; 
COMMAND(LGTH):=%15: 

TYPE:=MYCOMHAND(COHMAND, , i,PAPMCNT, 
PARMINFO, TABLE); 

IF < THEN GO ERROR? 

IF PARMCNTOl THEN GO ERROR; 

INDX:=PARMINFO-eCOMKAND; 

OPERAND : =B IN ARY( COMMAND ( I NDX) , 

PARMINFOC1) .(0:8)); 

IF <> THEN GO ERROR; 

CASE (TYPE-1) OF 
BEGIN 

ACCUM :=ACCUM+OPER AND; 
ACCUM :=ACCUM-OPER AND; 
ACCUM :=ACCUM»OPEPAND; 
ACCUM ;= ACCUM /OPERAND; 






END: 



RESULT: 



1 
1 
1 

1 
1 
1 
1 
1 
1 
RAGE 



ERROR: 



EXIT: 
=%020; 



=0:00:03; 



MOVE ANSWER(8):=" ": 
ASCI It ACCUM, 10, ANSWEPC8)): 
PRIfJT(OUTPUT,7,0) ; 
GO LOOP; 

PRINT(ERRMSG»7,0) : 
IF NOT INTERACTIVE THEN QUIT(2); 
GO LOOP; 
END. 

SECONDARY DB STOPAGE=%001 1 3 
NO. WARNINGS=000 
ELAPSED TIME=0:00:11 



<<PROGRAM ID>> 

?*h~> -: ctfe»'--> 

<<PPOMPT USER» 
<<GET COMMAND>> 
<<CHECK FOR ERROR>> 
<<DONE - EXIT>> 
<<CAPRIAGE RETURN» 

<<TAKE APART C0MMAND>> 

«NO COMMAND MATCH>> 
<<NO PARAMETERS>> 
<<SUBSCRIPT OF PARM>> 
<<CONVERT PARAMETER» 

<<CHECK FOR F.RR0R» 

<<SELECT OPERATION» 

<<ADD COMMAND>> 
<<SUB COMMAND>> 
«MUL COMMAND» 
«DIV COMMAND>> 
<<SET COMMAND>> 



<<RESET OLD ANSWER>> 
<<CONVERT ACCUM>> 
<<OUTPUT NEW ANSfcER>> 



tciumii'iuc wml 



' r«T1T HTTnM'^% 



«ERROR MESSAGE>> 
«NO LIVE USER-QUIT» 
<<CONTINUE CALCULATION>> 



Figure 4-2. Using the WHO Intrinsic 
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calls the WHO intrinsic to make this determination. If the logical identifier INTERACTIVE is 
TRUE (bit 15 = 1) after the WHO intrinsic executes, and job/session input file and job/session list 
file form an interactive pair, thus the user is running the program interactively. 

The statement 

IF INTERACTIVE THEN PRINT(REQ,1,%320); 

checks whether INTERACTIVE is TRUE or FALSE. If TRUE, the PRINT portion of the statement 
is executed and a prompt character (?) is displayed on the terminal to prompt the user for a 
command. 

CONVERTING NUMBERS FROM BINARY CODE TO ASCII STRINGS 

You can convert a one-word binary number to an octal or decimal number represented as an ASCII 
string with the ASCII intrinsic. The length of the resulting ASCII string can be returned as an 
integer value. 

The ASCII intrinsic call is illustrated in figure 4-3. The statement 

ASCII(ACCUM,10,ANSWER(8)); 

converts the one-word binary number contained in ACCUM to the base 10 and places the converted 
value into the 8th element of the byte array ANSWER. The length of the resulting ASCII string is 
unimportant in this application and therefore no variable is provided in the intrinsic call for this 
return. If the length were desired, the intrinsic call could have had the form 

LGTH: = ASCII (ACCUM, 10, ANSWER (8)); 

The DASCII intrinsic, which converts a double-word (32-bit) binary number to an octal or decimal 
number represented as an ASCII string, is shown in Figure 4-4. 

The statement 

LGTH: =DASCII(CNTR,10,BMSG(20) ) ; 

converts the 32-bit binary number contained in CNTR to the base 10 and places the converted 
decimal value in the 20th element of byte array BMSG. The length (number of characters) of the 
converted value is returned to LGTH. 

The value is converted from binary to ASCII so that it can be printed by the PRINT statement. 

CONVERTING NUMBERS FROM AN ASCII NUMERIC 
STRING TO A BINARY CODED VALUE 

The BINARY intrinsic converts an ASCII numberic string to its equivalent binary value. The con- 
verted value is returned to the calling program. 

The BINARY intrinsic call is illustrated in Figure 4-5. The statement 

OPERAND:=BINARY(COMMAND(INDX),PARMINFO(1).(0:8)); 

converts the ASCII numeric string contained in the element specified by INDX of the array COM- 
MAND to its binary equivalent. The length of the ASCII string is specified by the first 8 bits of the 
first word of the array PARMINFO. The resulting binary value is stored in the word OPERAND 
4-12 
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00001000 

00002000 

00003000 

00004000 

00005000 

00006000 

00007000 

00008000 

00009000 

00010000 

00010100 

00011000 

00012000 

00013000 

00014000 

00015000 

00016000 

00017000 

00019000 

00020000 

00021000 

00022000 

00023000 

00024000 

00025000 

00026000 

00027000 

00028000 

00028100 

00029000 

00030000 

00031000 

00032000 

00033000 

00034000 

00035000 

00036000 

00036100 

00037000 

00038000 

00039000 

00040000 

00041000 

00042000 

00043000 

00044000 

00045000 

00046000 

00047000 

00048000 

00049000 

00050000 

00051000 

00052000 

00053000 

00054000 



00000 
00000 



00000 1 



00011 
00007 
00007 
00007 
00010 
00010 
00001 1 
00010 1 
00016 1 
00016 1 
00016 1 
00016 1 



00016 1 
00016 1 
00016 1 
00016 1 
00016 1 
00016 1 
00004 1 
00010 1 
00010 1 
00016 1 
00023 1 
00026 1 
00040 1 
00043 1 



00043 1 

00050 1 

00056 1 

00057 1 
00062 i 
00065 1 
00070 1 



00075 
00076 



00076 1 



00100 1 
00106 2 
00116 2 
00122 2 
00126 2 
00133 2 
00136 / 
00143 1 
00143 1 
00155 1 
00163 1 



00170 
00171 
00171 



00175 1 

00201 1 

00202 1 



SCONTPOL USLINIT 
BEGIN 

ARRAY HEADING(0:8)!="INTEGER CALCULATOR"; 

ARRAY FFRMSG(0:6):="ILLECAL ENTRY."; 

ARRAY INPUT(0:36): 

BYTE ARRAY COMMAND C*)=INPUT; 

BYTE ARRAY ANSWERCO : 1 3) : =" ACCUM = "; 

ARRAY OUTPUT(»)=ANSWEF; 

BYTE ARRAY TABLECO : 25 ) : = 

5, 3, "ADD", 5, 3, "SUB", 5,3,"MUL", 
5,3, "DJV", 5, 3, "SET", 0; 

INTEGER ARRAY PARMINFO CO : 1) ; 

LOGICAL INTERACTIVE:=FALSE; 

INTEGER ACCUM:=0, OPERAND:=0, PEO:="? ", 
LGTH, INDX, PARMCNT, 



TYPE; 



INTRINSIC ASCI I, BINARY, READ, PRINT, MYCOMM AND, QUIT, WHO; 



<<END OF DECLARATIONSS 



loop: 



PRINT(HEADING,9,0) ; 
WHOCTNTERACT1VE) ; 

IF iwi'tKAC'll vr. incN ritiniinLuiinJiuil 

LGTH: =READC INPUT, -72); 

IF <> THEN GUITC1): 

IF CPMMAND="END" THEN GO EXIT; 

COMMAND(LGTH) :=%15: 

TYPE :=MYCOMM AND (COMMAND,, 1, PARMCNT, 
PARMINFO, TABLE); 

IF < THEN GO ERROR; 

IF PARMCNTOi THEN GO ERROR; 

INDX:=PARMINKO-eCQMMAND; 

OPERAND :=BINARY(COMMAND( INDX) , 

PARMINFO(l) .(0:8)) ; 

IF <> THEN GO ERROR; 

CASE (TYPE-1. ) OF 
BEGIN 

ACCUM :=ACCUM+OPER AND; 
ACCUM :=ACCUM-OPER AND; 
ACCUM :=ACCUM«OPEP AND; 
ACCUM := ACCUM /OPERAND; 
ACCUM:=OPERAND; 



RESULT: 



ERROR: 



EXIT! 
E=%020; 



PRIMARY DB STOPAG 
NO. ERRORS=O00; 
PROCESSOR TIME=0:00:03 



MOVE ANSWF.R(S) :=" "; 
ASCIICACCUM, 10,ANSWEP(a)); 
PRINT(OUTPUT,7,0) J 
GO LOOP; 

PRINT(ERPMSG,7,0); 
IF NOT INTERACTIVE THEN QUITC2); 
GO LOOP; 
END. 

SECONDARY DB STOPAGE=%001 1 3 
NO. WARNINGS=000 
ELAPSED TIME=0:00:11 



<<PR0GRAM ID>> 
<<LIVE USER?>> 

«PROMPT USER>> 
«GET COMMAND>> 
<<CHECK FOR ERROR>> 
<<DONE - EXITS 
<<CARRIAGE RETURNS 

<<TAKE APART COMMANDS 

«NO COMMAND MATCH>> 
<<NO PARAMETERSS 
<<SUBSCRIPT OF PARM>> 
<<CONVERT PARAMETERS 

<<CHECK FOR ERR0R>> 

«SELECT OPERATIONS 

<<ADD COMMANDS 

«SUB COMMAND» 

<<MUL C0MMAND» 

<<DIV COMMANDS 

<<SET COMMANDS 



<<RFSFT OLD ANSWERS 
«CONVERT ACCUM» 
«OUTPUT NEW ANSWERS 
<<CONTINUE CALCULATIONS 

<<ERROR MESSAGE>> 
«NO LIVE USER-QUITS 
<<C0NTINUE CALCULATION>> 



Figure 4-3. Using the ASCII Intrinsic 
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HEWLETT 


•PACKARD 32100A.05.1 SPL/3000 HON, NOV 3, 1975, 10:42 AM 


00001000 


00000 





SCONTPOL USLINIT 




00002000 


00000 





BEGIN 




00003000 


00000 


1 


ARRAY HEADINGCOMO) :="CONTROL Y TFAP EXAMPLE"; 


00004000 


00013 


1 


ARRAY MSG(0:15) :="COUNTER CURRENTLY 


- « • 
* 


00005000 


00020 


1 


BYTE ARRAY RMSGC*)=MSG; 




00006000 


00020 


1 


DOUBLE CNTR:=OD; 




00007000 


00020 


1 


INTEGER DUMMY, LGTH; 




00008000 


00020 


1 






00009000 


00020 


1 


INTRINSIC PRINT, XCONTRAP, QUIT, DASCI I, PESETCONTROL ; 


00010000 


00020 


1 






00011000 


00020 


1 


PROCEDURE CONTROLY; 




00012000 


ooooo 


1 


BEGIN 




00013000 


00000 


2 


INTEGER SDEC=0+1; 




00014000 


ooooo 


2 






00015000 


ooooo 


2 


LGTH;*DASeiItCNTR,10,BMSC(20}); 


«COKV£RT COUNTERS 


00016000 


00007 


2 


PPINT(MSG,16,0); 


<<OUTPUT COUNTER» 


00017000 


00013 


2 


RESETCONTROL: 


<<PEARM CONTROL Y TRAP» 


00018000 


00014 


2 


TOS:=%31400+SDEC; 


<<BUILD EXIT INSTRUCTIONS 


00019000 


00016 


2 


ASSEMBLECXEO 0); 


<<EXECUTE EXIT>> 


00020000 


00017 


2 


END; 




00021000 


OOOOO 


1 






00022000 


ooooo 


1 


<<END OF DECLAPATIONS>> 




00023000 


ooooo 


1 






00024000 


ooooo 


1 


PRINT(HEADING,11,0) ; 


<<PPOGRAM ID>> 


00025000 


00004 


1 


XCONTPAPCgCONTROLY, DUMMY) ; 


<<ARM CONTROL Y TRAP>> 


00026000 


00007 


1 


IF < THEN QUIT(l); 


<<CHECK FOR EPROR» 


00027000 


00012 


1 


LOOP: 




00028000 


00012 


1 


CNTR:=CNTR+1D; 


<<DOUBLE INCREMENT>> 


00029000 


00023 


1 


IF CNTROOOOOOOD THEN GO LOOP; 


<<CONTINUOUS LOOP>> 


00030000 


00027 


1 


END. 




PRIMARY 


DB STORAGE: 


:%007; SECONDARY DB STORAGE=%00033 




NO. EPRORS=000; 




NO. KARNINGS=000 




PROCESSOR TIME: 


0:00:02; ELAPSED TIME=0:00:26 






Figure 4-4. Using the DASCII Intrinsic 

To convert a number from an ASCII string to a double-word (32-bit) binary value, the DBINARY 
intrinsic is used. A DBINARY intrinsic call could be of the form 

DVAL : = DBINARY (STRING, LENGTH) ; 

where STRING contains the octal or decimal number to be converted and LENGTH is an integer 
representing the length of the string containing the ASCII-coded value. The converted double-word 
value is returned to DVAL. 

TRANSLATING CHARACTERS WITH THE CTRANSLATE INTRINSIC 

The CTRANSLATE intrinsic is used for character code translating, whether between the standard 
computer character codes or with a user-defined code. It permits you to obtain character code con- 
versions within programs of your own design. In the code parameter of CTRANSLATE, the follow- 
ing values specify the translation table to be used : 

- The user supplied table specified in the parameter, table. 

1 - EBCDIC to ASCII. (EBCDIC characters with no ASCII equivalent are translated to a byte 

of zero.) 

2 - ASCII to EBCDIC. (The ASCII parity bit is ignored.) 

3 - Reserved for future use. 
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00001000 00000 
00002000 00000 
00003000 00000 1 
00004000 00011 1 
00005000 00007 1 
00006000 00007 1 
00007000 00007 1 
00008000 00010 1 
00009000 00010 1 
00010000 00001 1 
00010100 00010 1 
00011000 00016 1 
00012000 00016 1 
00013000 00016 1 
00014000 00016 1 
00015000 00016 
00016000 00016 
00017000 00016 
00019000 00016 
00020000 00016 
00021000 00016 
00022000 00004 
00023000 00010 1 IjOOPs 
00024000 00010 
00025000 00016 
00026000 00023 
00027000 00026 
00028000 00040 
00028100 00043 
00029000 00043 
00030000 00050 
00031000 00056 
00032000 00057 
00033000 00062 
00034000 00065 
00035000 00070 
00036000 00075 
00036100 00076 
00037000 00076 
00038000 00100 
00039000 00106 
0004O000 00116 
00041000 00122 2 
00042000 00126 2 
00043000 00133 
00044000 00136 
00045000 00143 1 RESULT: 
00046000 00143 
00047000 00155 
00048000 00163 
00049000 00i70 
00050000 00171 1 ERROR: 
00051000 00171 
00052000 00175 
00053000 00201 
00054000 00202 1 EXIT: 
PRIMARY DB STORAGE=%020 : 
NO. ERRORS=0O0; 
PROCESSOR TIME=0:00:03; 



1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
J 
1 
1 

4 

X 

1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
2 
2 



SCONTPOL USLINIT 
BEGIN 

ARRAY HEADINGC0:8): = "INTEGF.R CALCULATOR"? 

ARRAY FRPMSG(0:6):="ILLEGAL ENTRY."; 

ARRAY INPUT(0:36); 

BYTE ARRAY COMMANDC»)=INPUT; 

BYTE ARRAY ANSWERCO : 1 3) :=" ACCUM = "i 

ARRAY OUTPUT(«)=ANSWEP; 

BYTE ARRAY TABLE C : 25 ): = 

5, 3, "ADD", 5, 3, "SUB", 5,3, "MUL" 
5,3,"DIV", 5, 3, "SET", 0; 

INTEGER ARRAY PARMINFOC : 1 ) ; 

LOGICAL INTERACTIVE:=FALSE; 

INTEGER ACCUM:=0, OPERAND:=0, PEQ:="? ", 
LGTH, INDX, PARHCNT, 



TYPE; 
INTRINSIC ASCI I, BINARY, READ, PRINT, MYCOMMAND, QUIT, tsHO; 



«END OF DECLAPATIONS>> 



PRINT(HEADING,9,0); 
WHO(INTERACTIVE); 

IF INTERACTIVE THEN PRINTCPEQ, 1 , %320 ) J 

LGTH:=READ (INPUT, -72); 

IF <> THEM QUIT(l): 

IF CPMMAND="END" THEN GO EXIT; 

COMMANDfLGTH) :=%I5; 

TvprjiMVCOMMANDCCOHMAND, , 1 ,PAPMCNT, 
PARMINFO, TABLE); 

IF < THEN GO ERROR; 

IF PARMCNTOl THEM GO ERROR; 

INpX:=PARMINKO-eCOMf-iMJD; 

,;rHHi);sh,,«Ku-J'Wwn INDX), 

PARMINFO(1).(0:?)); 

IF <> THEN GO EPPOP; 

CASE CTYPE-1) OF 
BEGIN 

accum:=accuh+operand; 
accum:=accum-op£rand; 
accum:=accum»opepand; 
accum:=accum /operand; 
accum:=operand; 
END; 

MOVE ANSWERC8):=" "! 
ASCII(ACCUM,10,ANSWEP(8)); 
PPINT(OUTPUT,7,0) ; 



PRINT(ERPMSG,7,0); 
IF NOT INTERACTIVE THEN QUITC21; 
GO LOOP; 
END. 

SECONDARY DB STORAGE=%001 1 3 
NO. WARNINGS=000 
ELAPSED TIME=0:00:11 



«PROGRAM ID>> 
«LIVE USER?>> 

<<PROMpT USER>> 
«GET COMMAND>> 
<<CHECK FOR ERROR>> 
<<DONE - EXIT>> 
<<CARRIAGE RETURN>> 

<<TAKE APART COMMAND» 

<<NO COMMAND MATCH>> 
«NO PARAHETERS>> 
<<SUBSC!^IPT OF pAPy>> 

iililililiiliiliillllii 

«."H-VF His FPhO?» 

<<SELECT OPERATION>> 

<<ADD COMMAND>> 
«SUB COMMAND» 
<<HUL C01MAND>> 
<<DIV COMMAND>> 
<<SET COMMAND>> 



«RFSET OLD ANSWER>> 
<<CONVERT ACCUM>> 
<<OUTPUT NEW ANSWER>> 
«C0NT1NUE CALCULATION» 

<<ERROR MESSAGE>> 
«NO LIVE USER-QUIT>> 
<<CONTINUE CALCULATION>> 



Figure 4-5. Using the BINARY Intrinsic 
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4 - Reserved for future use. 

5 - EBCDIK to JIS (Katakana data). 

6 - JIS to EBCDIK. 

As an example of converting from EBCDIC to ASCII, suppose the byte array ESTRING contains 
the EBCDIC characters "JOB 2". You want to convert this string to its ASCII equivalent and store 
it in the byte array ASTRING. The following intrinsic call could be used: 

CTRANSLATE(1,ESTRING,ASTRING,5); 

The parameters specified in the above intrinsic call are: 

code 1, which specifies the EBCDIC-to-ASCII table. A for this parameter 

specifies a user-defined translation table, and a 2 specifies the 
ASCII-to-EBCDIC table. 

instring ESTRING, a byte array containing the string to be converted. 

outstring ASTRING, a byte array which will contain the ASCII characters for 

"JOB 2" when the intrinsic is executed. 

stringlength 5, which specifies the length, in bytes, of the string "JOB 2". 



table 



Omitted. This parameter, if specified, consists of a byte array 
containing a user-defined table to be used in the translation. 



TRANSMITTING PROGRAM INPUT/OUTPUT FROM JOB/SESSION 
INPUT/OUTPUT DEVICES 

In addition to the FREAD and FWRITE intrinsics discussed in Section III, MPE provides three 
other intrinsics that allow you to read information from the job/session input device (READ and 
READX intrinsics) or write information to the job/session list device (PRINT intrinsic). 
Additionally, two other intrinsics allow you to transmit a message to the Operator's Console 
(PRINTOP intrinsic), or transmit a message to the Operator's Console and solicit a reply 
(PRINTOREPLY intrinsic). 

Please bear in mind that the READ, READX, and PRINT intrinsics are limited in their usefulness. 
The reason for this is that :FILE commands are not allowed with these intrinsics and the filenum 
parameter, obtained from the FOPEN intrinsic, is not available for use with these intrinsics. Usually, 
therefore, you will find it to be more convenient and better programming practice to use the 
FOPEN intrinsic to open the files $STDIN and $STDLIST, and then issue FREAD 's and FWRITE 's 
against these files. 

READING INPUT FROM THE JOB/SESSION INPUT DEVICE 

The job/session input device is the source of all MPE commands relating to a job or session, and is 
the primary source of all ASCII information input to the job or session. Normally, the input device 
is a terminal for sessions and a card reader for jobs. 
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You can read a string of ASCII characters from the job/session input device into an array in your 
program with the READ and READX intrinsics. The READ and READX intrinsics are identical 
except that the READX intrinsic reads input from $STDINX instead of $STDIN. ($STDINX is 
equivalent to $STDIN except that records with a colon in column 1 indicate the end of data to 
$STDIN and only the commands :EOD, :EOF, :JOB, :EOJ, and :DATA indicate the end of data for 
$STDINX.) 

The READ intrinsic call is illustrated in figure 4-6. 
The statement 

LGTH:=READ(INPUT,-72); 

reads an entry from the terminal and transfers this string to the array INPUT. The maximum length 
of the string to be read is specified as 72 bytes (-72). The actual length of the string read is returned 
and stored in the word LGTH when the intrinsic executes. 

The statement 

IF < > THEN QUIT(l); 

. ,, i.. ■••,• j„ ,_ j ;j? /~t/-i/-i -~~ r*r>T in •nfiimiyl +V>q QUIT intrinsic is 

checks for a "not equal' condition code anu, n kJ^^j Oi ^^±j io i^uiueu, **^ ^^ ^„„„..^ _ 
executed and the process is aborted. The (1) parameter is an arbitrary user-supplied value that is 
displayed as part of the abort message. 

WRITING OUTPUT TO THE JOB/SESSION LIST DEVICE 

Normally, the list device is a line printer for jobs and a terminal for sessions. You can write a string 
of ASCII characters from an array in your program to this list device with the PRINT intrinsic. 

In figure 4-6, the statement 

PRINT(HEADING,9,0); 

transmits the string "INTEGER CALCULATOR" from the array HEADING (see statement number 
3 in figure 4-6). The length parameter is specified as 9, which means that the string to be 

transmitted is y woros long (a negauve vaiue wumu a^c^u-jr vj***,,. j.*^. ~~..~.~~ t — . -, 

signifying that the full record is to be printed, up to 132 characters per line, using single spacing. 

WRITING OUTPUT TO THE OPERATOR'S CONSOLE 

The PRINTOP intrinsic can be used to transmit an ASCH string from an array in your program to 
the Operator's Console. The ASCII string to be transmitted is limited to 56 characters. 

The PRINTOP intrinsic could be called as follows: 

PRINTOP(MESSAGE,10,0) ; 

The character string to be transmitted is contained in the array MESSAGE. The parameter 10 
signifies that the message is 10 words long. A negative value for this parameter would specify bytes. 
If zero is specified for the length parameter, only the standard message prefix is written on the 
Operator's Console; the string contained in MESSAGE would not be transmitted in this case. 
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BYTE ARRAY COMMAND C*)=INPUT; 
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BYTE ARRAY ANSWERCO : 1 3 ) :=" ACCUM = " 
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ARRAY OUTPUT(»)=ANSWER; 
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5,3,"DIV", 5, 3, "SET", 0; 




00011000 


00016 


1 


INTEGER ARRAY PARHINFO(0 : 1 ) ; 
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LOGICAL INTERACTIVE:=FALSE: 
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INTEGER ACCUM:=0, OPERAND:=0, REQ:="? ", 




00014000 


00016 
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LGTH, INDX, PARHCNT, 


TYPE; 
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00016000 
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INTRINSIC ASC1I,BINARY,READ,PRINT,MYC0MMAND,QUIT,WH0; 


00017000 
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<<END OF DECLARATIQNS>> 
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00004 
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WHO(TNTEPACTIVE): 


<<LIVE USER?» 


00023000 
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1 


LOOP: 




00024000 
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1 


IF INTERACTIVE THEN PRINTt PEG. 1 , %320) J 


<<PPOMPT USER>> 
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00016 


1 


LGtHt*REAi*(I»inJT,'»72)i 


«SET jCOMMA»D» 
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IF <> THE* OVITCUj 


"' «CmM- FQ«-;. E*IR01&* : 


00027000 


00026 
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IF COMMAND="END" THEN GO EXIT; 


«DONE - EXIT» 


00028000 


00040 


1 


COHHAND(LGTH):=%J5: 


<<CARRIAGE RETURN>> 


00028100 


00043 


1 






00029000 


00043 
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TYPE :=MYCOMM AND (COMM AND,, 1,PAPMCNT, 


<<TAKE APART C0MMAND>> 


00030000 


00050 


1 


PARMINFO, TABLE); 




00031000 


00056 


1 


IF < THEN GO ERROR; 


<<NO COMMAND MATCH» 


00032000 


00057 


1 


IF PARMCNTOl THEN GO ERROR; 


«NO PARAMETERS» 


00033000 


00062 


1 


INDX:=PARMINFO-G>COMMAND; 


<<SUBSCRIPT OF PARM>> 


00034000 


00065 


1 


OPERAND : =B IN ARYC COMM AND (INDX), 


<<CONVERT PARAMETER» 


00035000 


00070 
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PARMINFO(n.(0:81); 




00036000 


00075 


1 


IF <> THEN GO ERROR; 


<<CHECK FOR ERROR>> 


00036100 


00076 


1 






00037000 


00076 


1 


CASE (TYPE-1) OF 


<<SELECT OPERATION» 


00038000 


00100 


1 


BEGIN 




00039000 


00106 


2 


ACCUM :=ACCUM+OPER AND; 


<<ADD COMMAND>> 


00040000 


00116 


2 


ACCUM:=ACCUM-OPERAND; 


<<SUB COMMAND>> 


00041000 


00122 


2 


ACCUM:=ACCUM»OPEPAND; 


<<MUL C0MMAND» 


00042000 


00126 


2 


ACCUM :=ACCUM/OPER AND; 


<<DIV C0MMAND>> 


00043000 


00133 


2 


ACCUM;=OPERAND; 


<<SET C0MMAND>> 


00044000 


00136 


7 


END; 




00045000 


00143 


1 


RESULT: 




00046000 


00143 


1 


MOVE ANSWER(8):=" "; 


<<RESET OLD ANSWER>> 


00047000 


00155 


1 


ASCII (ACCUM, 10, ANSWEPC8)) ; 


<<CONVERT ACCUM» 


00048000 


00163 


1 


PRINT(OUTPUT,7,0); 


<<OUTPUT NEW ANSWER>> 


00049000 


00170 


1 


GO LOOP; 


<<C0NTINUE CALCULATION>> 


00050000 


00171 


1 


ERROR: 




00051000 


00171 


1 


PRINT(ERRMSG,7,0); 


<<ERR0R MESSAGE>> 


00052000 


00175 


1 


IF NOT INTERACTIVE THEN QUITC2); 


<<NO LIVE USER-QUIT>> 


00053000 


00201 


1 


GO LOOP; 


<<C0NTINUE CALCULATION>> 


00054000 


00202 


1 


EXIT: END. 




PRIMARY 


DB STORAGE: 


:%020; SECONDARY DB STORAGE=%001 1 3 




NO. ERPORS=000 




NO. WARNINGS=000 




PROCESSOR TIME: 


=0:00:03; ELAPSED TIME=0:00:11 





Figure 4-6. Using the PRINT and READ Intrinsics 
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WRITING OUTPUT TO THE OPERATOR'S CONSOLE AND REQUESTING A REPLY 

The PRINTOPREPLY intrinsic can be used to transmit an ASCII string from an array in your 
program to the Operator's Console and to request that a reply be returned. For example, a program 
could ask the operator if the line printer contains a certain type of form. If the response is 
affirmative, the program then could write information on these forms. 

A PRINTOPREPLY intrinsic call could be as follows: 

REPLGTH : =PRINTOPREPLY (MESSAGE, 18,9, REPLY,-3 ) ; 

The following parameters were specified in the above call: 

message An ASCII string contained in the array MESSAGE. 

length 18 words. A negative value would specify bytes. If zero is specified for 

the length parameter, only the standard message prefix is written on the 
Operator's Console; the string contained in MESSAGE would not be 
transmitted in this case. 

control 9 (MPE ignores this parameter). 

re ply The operator's reply will be returned to the array REPLY. 

expectedl -3, signifying that the maximum expected length of the reply is 3 bytes. 

A positive value would specify words. 

The actual length of the operator's reply is returned to REPLGTH. This is a positive value 
representing a byte count in this case because expectedl is negative (-3). If expectedl is positive, 
then the length returned represents words. 

SUSPENDING THE CALLING PROCESS 

The calling process can be suspended with the PAUSE intrinsic. A PAUSE intrinsic call could be as 
follows: 

PAUSE(INT); 

INT is a real variable that specifies the amount of time, in seconds, that the process is suspended. 
The maximum interval allowed is approximately 2,147,484 seconds. 

When INT seconds have elapsed, control is returned to the calling process and execution resumes at 
the statement following the PAUSE intrinsic call. 

REQUESTING A PROCESS BREAK 

D"iW „ ,w««nn. vou can initiate a break programmatically with the CAUSEBREAK intrinsic. Using 
this intrinsic is the programmatic equivalent of using the BREAK key in a session, and allows you to 
enter certain MPE commands to perform functions such as creating a file or transmitting an 
informal message. The MPE commands permitted during a break are listed below: 
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:ABORT 


:IF 


: RESUME 


SPEED 


:ALTSEC 


:LISTF 


:SAVE 


STORE 


:ALTVSET 


:LISTVS 


:SECURE 


STREAJV 


:BUILD 


:MOUNT 


:SETCATALOG 


TELL 


:BYE 


:NEWVSET 


:SETDUMP 


TELLOP 


:COMMENT 


:PTAPE 


SETJCW 


VSUER 


:DEBUG 


:PURGE 


SETMSG 




rDISMOUNT 


:REDO 


SHOWCATALOG 




:DSLINE 


RELEASE 


SHOWDEV 




:DSTAT 


REMOTE HELLO 


SHOWIN 




:ELSE 


RENAME 


SHOWJCW 




:ENDIF 


REPORT : 


SHOWJOB 




:FILE 


RESET : 


SHOWME 




.GETRIN 


RESETDUMP 


SHOWOUT 




:HELP : 


RESTORE : 


SHOWTIME 





See the MPE Commands Reference Manual for discussions of commands. 
The form of the CAUSEBREAK intrinsic call is 
CAUSEBREAK; 

Execution of the process can be resumed where the interruption occurred by entering the command 

: RESUME 
The CAUSEBREAK intrinsic is not valid in a job. 

TERMINATING A PROCESS 

You can programatically terminate a process with the TERMINATE intrinsic. The process and all of 
its descendants, including any extra data segments belonging to them, are deleted. 

All files still open by the process are closed and assigned the same disposition they had when 
opened. 

The form of the TERMINATE intrinsic call is 
TERMINATE; 

ABORTING A PROCESS 

If called from within any process in a user-process structure, the QUIT intrinsic aborts that process. 

The QUIT intrinsic sets the job /session in an error state and transmits a Type 2 abort message to the 
calling process' list device. In a session, the process is aborted but the session remains active when 
the entire program finishes. In a batch job, the job terminates when the entire program finishes 
unless the : CONTINUE command (see the MPE Commands Reference Manual) has been included as 
part of the job. 

Figure 4-7 shows the QUIT intrinsic being called if a READ statement did not execute properly. 
The abort message resulting from the QUIT intrinsic execution is shown below. 



ABORT :SPROG.PUB.TECHPUBS.%0.%26 
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SCONTFOL USLINIT 
BEGIN 

ARRAY HEADING(0:8):="INTEGER CALCULATOR"; 

ARRAY FPRMSG(0:6):="ILLEGAL ENTRY."? 

ARRAY INPUT(0:36); 

BYTE ARRAY COMMANDC»)=INPUT; 

BYTE ARRAY ANSWERCO : 1 3) : =" ACCUH = "; 

ARRAY OUTPUT(»)=ANSWEP; 

BYTE ARRAY TABLECO : 25 ) : = 

5, 3, "ADD", 5, 3, "SUB", 5,3, "MUL", 
5,3,"DIV", 5, 3, "SET", 0; 

INTEGER ARRAY PARMINFO(0 : 1) ; 

LOGICAL INTERACTIVE: =FALSE; 

INTEGER ACCUM;=0, OPERAND:=0, PEQ:="? ", 

LGTH, INDX, PARHCNT, TYPE; 

INTRINSIC ASCI I, BINARY, READ, PRINT, MYCOMM AND, QUIT, t*HO; 



<<END OF DECLAPATIONS>> 



PRINT(HEADING,9,0); 
WHOCTNTERACTIVE); 



«PROGRAM ID>> 
<<LIVE USER?>> 



LOOP? 



IF INTERACTIVE THEN PRINTC>-'I l,1,%370)» **Pf< u ^ !><5fO>> 

LC,?K;sP«,iM:M i»$>rT„*72\ : «Q?.l fOM«A'*&»> 

TF t> Jin, ttUITtDj «':-M,Hs FOR £|>ROR» 

IF COMHAND="ENb" THEN 'GO EXIT; <<DONE - EXIt>> 

COHMAND(LGTH):=%15; «CARRIAGE RETURN» 



RESULT! 



TYPE :=MYCOMM AND (COMMAND , ,1,PAPMCNT» 
PARMINFO, TABLE); 

IF < THEN GO ERROR; 

IF PARMCNTOl THEN GO ERROR; 

INDX:=PARMINFO-PCOMMAND; 

OPERAND : =B IN ARYC COMMAND t INDX), 

PARMINFO(l) .(0:8)); 

IF <> THEN GO ERROR; 

CASE CTYPE-1) OF 
BEGIN 

accum:=accum+operand; 
accum:=accum-operand; 
accum;=accum*opepand; 
accum:=accum /operand; 
accum:=operand; 

END; 
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PRIMARY 


DB STORAGE 


NO. ERPORS=000 




PROCESSOR TIME: 


=0:0 



ERROR; 



EXIT: 
:%020; 



0:03; 



MOVE ANSWER(8):=" ": 
ASCII(ACCUM,10,ANSWEP(8)); 
PRINT(0UTPUT,7,0) : 

Gu UUl-T } 

PRINTCEPRMSG,7,0): 

IF NOT INTERACTIVE THEN QUITC2); 
GO LOOP; 
END. 

SECONDARY DB STORAGE=%001 1 3 
NO. WARNINGS=000 
ELAPSED TIME=0:00:11 



«TAKE APART COMMAND» 

«NO COMMAND MATCH>> 
<<NO PARAMETERS» 
<<SUBSCRIPT OF PARM>> 
<<CONVERT PARAMETERS 

<<CHECK FOR EPROR» 

«SELECT OPERATION>> 

<<ADD CO-'iMAND>> 

<<SUB COMMAND» 

«MUL COMMAND» 

<<DIV COMMAND>> 

<<SET COMMAND>> 



«RESET OLD ANSWER>> 
<<CONVERT ACCUM>> 
«OUTPUT NEW ANSWER» 
<<CONTINUE CALCULATIONS 

«ERROR MESSAGE>> 
<<NO LIVE USER-QUIT>> 
«CONTINUE CALCULATION» 



Figure 4-7. Using the QUIT Intrinsic 
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The statement 

IF< >THENQUIT(1); 

checks for a "not equal" condition code and, if CCG or CCL is returned, the QUIT intrinsic is 
called. The process is aborted and the abort message is printed. The QUIT parameter (1) is an 
arbitrary number supplied by the user and can be used to identify a specific QUIT intrinsic call in 
case of multiple possible QUIT intrinsic calls. This number, 1 in this case, is printed at the end of 
the abort message (P=l). The system job control word (JCW) is set to the value FATAL, with the 
QUIT parameter as a modifier. In this example, JCW would be set to FATAL1, or %1 00001. 

ABORTING A PROGRAM 

You can programmatically abort the entire user-process structure (program) with the QUITPROG 
intrinsic. This intrinsic destroys all processes up to, but not including, the job/session main process. 

In batch jobs not containing the :CONTINUE command (see the MPE Commands Reference 
Manual), this terminates the job. 

The form of the QUITPROG intrinsic call could be as follows: 

QUITPROG(l); 

The parameter (1) can be any user-specified number. When the QUITPROG intrinsic executes, this 
number is printed as part of the abort message. In addition, QUITPROG sets the system job control 
word (JCW) to the value FATAL, with the QUITPROG parameter as a modifier. Thus, in this 
example, JCW would be set to FATAL1, or %100001. 



CHANGING STACK SIZES 

When you prepare or execute a process, you specify (or allow MPE to assign by default) the size of 
the stack (Z to DB) area and the user-managed (DL to DB) area within the stack segment. Once the 
process begins execution, you can programmatically change the size of these areas, to meet new 
requirements as they arise, by altering the register offsets Z to DB or DL to DB. For example, you 
typically expand the size of these areas when you find, during process execution, that the sizes 
specified initially were not sufficient for your data requirements. Conversely, you might contract 
the size of either of these areas should your process no longer require large amounts of space for 
data. (This is a good practice — it improves overall system performance.) These changes are 
requested with the DLSIZE intrinsic for the DL to DB area and the ZSIZE intrinsic for the Z to DB 
area. 

If you plan to expand or contract the Z to DB or DL to DB areas programmatically, you must 
specify, at the time the stack is created, the anticipated maximum size of the stack segment. This 
value is used by MPE in allocating disc storage. The maximum stack size value is specified at 
preparation or run time with the segsize parameter of the :PREP, :PREPRUN, or :RUN command, 
or if you are a user with the Process-Handling Capability, after the program is running with the 
maxdata parameter of the CREATE intrinsic. 
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NOTE 

When the stack segment belonging to a process running in 
privileged mode is frozen in main memory (during an 
input/output operation, for example), either implicitly (when 
a user's process interfaces directly with the input/output 
system), or explicitly (by a direct call to system intrinsics), 
the intrinsics to change the register offsets DL to DB or Z to 
DB cannot be executed. When these intrinsics are called 
under such circumstances, a special FROZEN STACK error 
code is returned to the calling process, which then may 
attempt recovery. In general, this error implies that you 
should wait until the stack is unfrozen before re-issuing the 
intrinsic call. 

CHANGING THE DL TO DB AREA SIZE 

You can expand or contract the area between DL and DB within the stack segment with the 
DLSIZE intrinsic. All current information within the DL to DB area is saved on expansion. On 
contraction, data within the area to be contracted is lost. See figure 4-8. 

A request for contraction less than the initial DL size of the area causes the initial DL size to be 
granted and an error condition code (CCL) to be returned. If the size requested causes the stack to 
exceed the maximum size permitted by the stack area, Z to DL, only this maximum will be granted. 

Some possible applications for the DL area are: 

• Dynamically allocated I/O buffers when using the FCOPY subsystem. 

• Compiler symbol tables when programming in SPL. 

• Global storage area for library routines in Segmented Libraries. These routines typically 
have no global area storage which will retain values assigned to them between calls to the 
procedure. These routines also typically have no common storage where data can be 
shared by several procedures. If you define your conventions carefully, these library 
routines can use the DL area of the process which calls them for this kind of storage, care 
must be taken, however, because the first 10 words of the DL area are reserved for 
subsystem use, and some system routines make use of the DL area for their own storage. 
Ac i™« oc ™nr onvirnnmpnt is comDletelv known and well defined, your main program 
or your library routines can get DL space and manage it as they choose.. 

Figure 4-9 contains an SPL program that expands and contracts the DL to DB area. 

NOTE 

All addressing within the DL to DB area is DB-relative 
neeative indexing and SPL is the only language, at present, 

■ - -<j— - - ■ - v 

which can access this area for you. 
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A CALL TO DLSIZE TO EXPAND THE 
DL TO DB AREA CAUSES THE DL 
REGISTER TO BE MOVED FARTHER 
AWAY FROM DB. THE NEW AREA 
CREATED BY THE EXPANSION IS 
ADDED TO THE EXISTING DL AREA. 
INFORMATION WHICH WAS CONTAINED 
IN THE OLD DL AREA IS NEITHER 
MOVED RELATIVE TO DB NOR ALTERED 
IN ANYWAY. 




DATA 
LOST 



A CALL TO DLSIZE TO CONTRACT THE 
DB TO DL AREA CAUSES THE DL 
REGISTER TO BE MOVED CLOSER TO 
DB. THE DATA CONTAINED BETWEEN 
THE OLD POSITION OF DL AND THE NEW 
CONTRACTED POSITION OF DL IS LOST 
TO THE USER. 



Figure 4-8. Expanding and Contracting the DL to DB Area 
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The program in figure 4-9 reads data from $STDIN and stores it in the DL area at progressively 
lower (DB - n) addresses. Additional DL space is allocated when the next buffer would he outside 
the current DL area. When a null record (0 length) is read, the program outputs the data on a 
last-in-first-out basis. After all the records are output, the DL space is collapsed to its initial 
allocation and the operation begins again. The loop is terminated by entering :EOD m place of a 
data line. 

NOTE 

The program was PREPed with a MAXDATA = 2000 
parameter. 

The statement 

TOTALDL :=DLSIZE(0) ; 
sets the DL to DB area to the original value assigned when the process was created (initial DL). 
Observe the following illustration of the DL to DB area. 



UL 



DB-46 



DB 




riDiniMAi pi I imit 

wril Oi ITirii— Lri. bum ■ 



36 WORDS RESERVED FOR BUFFER 



10 WORDS RESERVED FOR SYBSYSTEMS OF MPE 



Statement number 8 in the program 

LOGICAL POINTER BUFFER:=-46; 
sets a pointer to DB - 46, which is the DB-relative address of the first word in BUFFER. 
The statement 

PUSH(DL); 
pushes the DL register contents onto the top of the stack and the statement 

IF TOS > ©BUFFER THEN 

checks if the address of the first word of BUFFER is outside the DL to DB area. In other words, 
TOS contains the DL address from the DL register. If this value is greater than (less negative) than 
the address of the first word in BUFFER, then BUFFER is outside the DL to DB area. See below. 
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DB-154 



DL 
(DB - 128) 

DB-82 



DB-46 

DB-10 
DB 



36 WORDS 



BUFFER 
(36 WORDS) 



BUFFER 
(36 WORDS) 



BUFFER 
(36 WORDS) 



STARTING ADDRESS OF NEXT BUFFER 
IF ANOTHER RECORD READ FROM $STDIN 



If the DL address is DB - 128, then when only one buffer is filled, the address of the next buffer is 
well within the DL to DB area. When three buffers have been filled, however, the starting address of 
the next buffer (DB - 154) would be outside the DL to DB area (DB - to DB - 128). The TOS 
(DB - 128) is greater than the address of the first word in the next buffer (DB - 154). 



program 



If the next buffer would lie outside the DL to DB area, the next four statements in the 

BEGIN 

TOTALDL:=DLSIZE(TOTALDL-128); 
IF < > THEN QUIT(4); 
END; 

add 128 more words to the DL to DB area. 

The statements 

BUFFER:=" "; 

MOVE BUFFER(1):=BUFFER, (35); 

fill BUFFER with blanks preparatory to reading the input from $STDIN. A prompt is displayed and 
the user enters the next record. The length of the record is assigned to LGTH. 

If LGTH = 0, signalling a carriage return (no data entered), the program addresses the previous 
buffer and transfers control to LINEOUT. The contents of the buffers are written on $STDLIST on 
a last-in-first-out basis. When the original address is reached (DB - 46), control is returned to 
RESTART and the procedure is repeated. 

The statement 

TOTALDL : =DLSIZE(0) ; 

contracts the DL to DB area back to its original size, destroying the contents of all buffers. An 
:EOD entry terminates program execution. 



Figure 4-10 shows the results when the program is run. 
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PAGE 0001 HEWLETT-PACKARD 32100A.05.1 SPL/3000 THU, NOV 6, 1975, 11:12 AM 

00001000 00000 SCONTROL USMNIT 

00002000 00000 BEGIN 

00003000 00000 1 INTEGEP IN,OUT,LGTH, 

00004000 00000 1 TOTALDL:=0: 

00007000 00000 1 LOGICAL.. PROMPT:.-".: ; «W**P« ^W«IfPP«ii 

OOOOBOPi OOOOO 1 LOGICAL POINTER BUFFER:*-46; «B«FFER:36 ; R£SERVED:10» 

00009000 0000 i 

00010000 00000 1 INTRINSIC FOPEH , DLSIZE,FREAD, FWPITE,QUIT; 

00011000 00000 1 

00012000 00000 1 «END OF DECLAPATIONS» 

00013000 00000 1 „.....„., 

00014000 00000 1 IN:=FOPEN(,%44); «SSDTIN» 

00015000 00007 1 IF < THEN OUITCDl «CHECK FOP ERROP» 

00016000 00012 1 .«.«,„, tch-^ 

00017000 00012 1 0UT:=F0PEN(,%414,1); «SSTDLIST» 

00018000 00022 1 IF < THEN 0UITC2) ; «CHECK FOR ERROR» 

00018100 00025 1 RESTART; 

00018200 00025 

00018300 

nnnionnn 0003* 1 L1NEIN: ^^-^w^oai-ii™™™ 

00020000 00033 1 PUSH«M,)j ««« "*^^ M 5«TT1«G» 

00021^00 00034 1 IF TOS>*BWFFE« THEN ««EXT BUFFER OUTSIDE DL ? » 

00022000 00036 1 REG If 

00023000 

00024000 00043 

00025000 00046 2 

00028000 OOOSO ! MOVF^HUFFF.Rn )i .BUFFER, ( 35) | «BLANK READ 6UFFER» 

oSo2900n ' 1 rwRIW(OUT,FROI«PT.t,%320)! «J MOKPI WS MW» 

00030000 00062 i IF <> «M 0UI*C5>. «««* TO* ffclW«» 

00031000 00065 1 LGTH;^FREAI>i lN,8VmW, 36) r <*tm*T P***>> 

000 2000 00073 1 IF < THE* QUITtH, ««*CK FDP n«M>> 

00033000 00076 1 I? > THEN GO EXIT; U f , U ., 

00034000 00077 1 IF LGTHsO THM «»0 M« IW«?» 

'" ' r " : "° 2 9 ^BUFFER :=(»BUFFEJU 36; «AODPESS PREVIOUS BUFFER» 

$ CO UNEOUTs ' «STWf OUTPUT J^\5E>'» 



„„„„ 1 " inTM-I:=I.|.?liEfO>! <«KT 3L TO i'HIIM. 51ZS>> 

00030 i I" <! THEN QUIT (3): «CHECK FOR ERROR» 



ooo36 2 ' n r;.:rit-r'LM.-.KtTciAr,rL-!2h): «nv.\ "upe ?i asea»* 

2 I-' «* THft^f Q»1TC4); «rHK'K F"R i:p^^-» 



00036000 00102 
00037000 00105 
00038000 00113 2 •" ■ 



1 aMTFER:=<*R'.'FhEF<-ll-: «HDf.RF.K« NEXT buFFF.»>> 



GO ilNEIN; " '"" «cr«l'JU» »: 



00039000 00113 

00040000 00116 1 

00041000 00117 1 LINF.OUT: 

QOO42000 00117 1 FWRITECOUT, BUFFER, 36,0): «OUTPUT_DATA>> 

00043000 00124 1 IF <> THEN QUITC7); «CHfcCK roR tKKOR» 

S 0044000 Hill 1 IF ,BUFFER>=-46 THEN GO RESTART: "JIS""™";;"^ ^ll>l 

00050000 00132 1 pBUFFER:=PBUFFER+36 : «ADDRESS PREVIOUS BUFFER» 

000M000 00135 1 GO LINEOUTr «CONTINUE OUTPUT PHASE» 

00053000 00137 1 EXITtEND. 

PRIMARY DB ST0RAGE=%006 ; SECONDARY DB STLJRAOts 

NO. ERRORS=0O0; NO. WARNINGS=000 

PROCESSOR TIHE=0:00:03; ELAPSED TIME=0:00:22 



Figure 4-9. Using the DLSIZE Intrinsic 
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? ** * ***** * * * * * * * ****** 

? ******************* 

? ***************** 

? *************** 

? ************* 

? *********** 

? ********* 

? ******* 

? *** 

? * 

•5 

* 
*** 

J|C Jf, ^C ^p ^C 

******* 

********* 

*********** 

************* 

*************** 

***************** 

****** ************* 

****************** *** 

? d:;dddd 
? fvXNr'icj 

? EEEEEE 

? EEEEE" 
? HHHHHH 
? TTTT~T 

J : - J I i 

V- H* V "-T M H 



NNNNMs! 
DDDDDD 
? :EOD 

E.\'D CF ?~C3RAN 



Figure 4-10. Changing the DL to DB Area Size 
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CHANGING THE Z TO DB AREA SIZE 

You can alter the size of the current Z to DB area by adjusting the register offset of the Z address 
from the DB address with the ZSIZE intrinsic. 

The ZSIZE intrinsic moves the Z address forward (expansion) or backward (contraction) as shown 
below. 



NEWZ 





EXPANSION 



NEWZ I t- 

I BACKWARD ' 

z I 1 

CONTRACTION 



If the Z to DB area size requested exceeds the maximum size permitted for the Z to DL (stack) 
area, only the maximum size allowed is granted. 

All changes to the Z to DB area are made in increments or decrements of 128 words, thus the size 
actually granted may differ from the size requested. For example, if the present Z to DB area size is 
128 words, a request for a size of 129 words would result in a size of- 256 words being granted. 

A ZSIZE intrinsic call could be 

A OTCT7TT. = 7ffT , 7T5 , Y9?;m- 

If the maximum size for the Z to DL area permitted, an actual size granted for the Z to DB area of 
256 words would be returned to ACTSIZE. 

ENABLING AND DISABLING TRAPS 

Normally, whenever a major error occurs during the execution of a hardware instruction, a 
procedure from the System Library, or an intrinsic called by a user, the user program is aborted and 
an error message is output. You can, however, avoid immediate abort by enabling any of three 
software traps provided by MPE: 

The arithmetic trap, for hardware instruction errors. 

The library trap, for errors detected during execution of a system library procedure. 

The system trap, for errors detected during execution of a system intrinsic. 
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When an error occurs, the corresponding trap, if enabled, suppresses output of the normal error 
message, transfers control to a trap procedure defined by you, and passes one or more parameters 
describing the error to this procedure. This procedure may attempt to analyze or recover from the 
error, or may execute some other programming path. Upon exiting from the trap procedure, control 
returns to the instruction following the one that activated the trap. In the case of the library trap, 
however, you can specify that the process be aborted when control exits from the trap procedure.' 
Trap intrinsics can be invoked from within trap procedures. 

NOTE 

The validity of a trap procedure, specified by the external- 
type label of the user trap procedure {plabel), depends on the 
code domain of the caller's code and executing mode 
(privileged or non-privileged), and on the code domain of the 
plabel and the mode (privileged or non-privileged). The code 
domains are: 

PROG (User Program) 

GSL (Group SL) 

PSL (Public SL) 

SSL (System SL, non-MPE Segments) 

MPESSL (System SL, MPE Segments) 

If, at the time of enabling a trap procedure, the code of the caller is 

1. Non-privileged in PROG, GSL, or PSL: plabel must be non-privileged in PROG, GSL or 
PSL. 

2. Privileged in PROG, GSL, or PSL plabel may be privileged or non-privileged in PROG, 
GSL, or PSL 

3. Privileged or non-privileged in SSL: plabel may be in any non-MPESSL segment. 

ARITHMETIC TRAPS 

There are two levels of arithmetic traps: the hardware arithmetic trap set and the software 
arithmetic trap. Each trap in the hardware trap set detects a particular type of hardware error, such 
as division by zero or result overflow. The software trap, if enabled, receives an internal interrupt 
signal from a hardware trap when an error is encountered, and transfers control to a user trap 
procedure. 

When a user process begins execution, all hardware trap set interrupt signals are enabled 
automatically, but the software trap is disabled, permitting any hardware error to abort the process. 
Through intrinsic calls, however, you can alter the ability of the hardware trap set to send signals, 
and that of the software trap to receive a signal from any particular hardware trap. Only signals 
received and accepted by the software trap can invoke a user trap procedure. 

To enable or disable the internal interrupt signals from all hardware arithmetic traps, you enter the 
ARITRAP intrinsic call, as follows: 

ARITRAP(STATE); 

where STATE is TRUE (bit 15 = 1) to enable the signals from all hardware traps, and FALSE (bit 
15 = 0) to disable these signals. 
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When a software arithmetic trap procedure is executed, the Index register contains the word of code 
being executed when the trap occurred. This information, plus, if necessary, the right stackop bit in 
the stacked status word, can be used to identify the offending instruction. A one-word parameter is 
available, in Q - 4, in which certain bits indicate the type of hardware trap invoked. The various 
traps leave the parameter in Q - 4 as follows. 

STANDARD TRAPS 

Bit 15 = Floating Point Divide by 

14 = Integer Divide by 

13 = Floating Point Underflow 

12 = Floating Point Overflow 

11 = Integer Overflow 

A return from the trap procedure (through an (EXIT1) instruction) will resume execution in the 
user code domain at the instruction following that which activated the trap procedure. The 
condition of the stack when the trap procedure is invoked is 



Q-4 

Q 



User Program 



Hardware Trap Type 
Parameter 



Stack Marker 



Arithmetic 

Trap 
Procedure 



EXTENDED PRECISION FLOATING-POINT TRAPS 

Bit 10 = Extended Precision Overflow 
9 = Extended Precision Underflow 
8 = Extended Precision Divide by 

The address of the result operand is left on the stack in Q-5. An (EXIT 2) return will resume 
execution in the user code domain at the instruction following the one which caused the trap. The 
condition of the stack when the trap procedure is invoked is 



Q-5 
Q-4 

Q 

S 



User Program 



Result Address 



Hardware Trap Type 
Parameter 



Stack Marker 



Arithmetic 
Trap Procedure 
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COMMERCIAL INSTRUCTION TRAPS 

Bit 7 = Decimal Overflow 

6 = Invalid ASCII Digit (CVAD) 

5 = Invalid Decimal Digit 

4 = Invalid Source Word Count (CVBD) 

3 = Invalid Decimal Operand Length 

2 = Decimal Divide by 

The parameters stacked for the execution of the instruction are left on the stack below Q-4. To 
return properly the trap handler must examine the opcode (found in the Index Register) to 
determine the proper stack decrement to use on exit. The condition of the stack when the trap 
procedure is invoked is 



Q-4 
Q 



User Program 



Stacked Operands 



Hardware Trap Type 
Parameter 



Stack Marker 



Arithmetic 

Trap 
Procedure 



An arithmetic trap procedure is shown in figure 4-11. The procedure FDIVZRO is a trap proce- 
dure to which control is passed if a floating point divide by zero software trap is enabled and 
a program attempts an operation to divide by 0. 

The statement 

XARITRAP(%l,@FDIVZRO,DUMMYl,DUMMY2); 

enables the floating point divide by trap. The parameter %1 (bit 15 = 1) enables only the floating 
point divide by 0; the @FDIVZRO passes the trap procedure as a parameter; DUMMY1 and 
DUMMY2 are dummy parameters. 

The statement 

RESULT:=NUM/DENOM; 

attempts a floating point divide by operation and, since the floating point divide by trap is 
enabled, control is transferred to procedure FDIVZRO. The condition of the stack at this point is 



4-32 



PAGE 0001 HEWLETT-PACKARD 32100A.OS.1 SPL/3000 FP1, OCT 31, 1975, 11:01 AM 



00001000 
00002000 
00003000 
00004000 
00005000 
00006000 
00007000 
00008000 
00009000 
00010000 
00011000 
00012000 
00013000 
00014000 
00015000 
00016000 
00017000 
00018000 
00019000 
00020000 
00021000 
00022000 
00023000 
00024000 
00025000 
00026000 
00027000 
00027100 
00028000 
00029000 
00030000 
00031000 
00032000 
00033000 
00034000 
PRIMARY 
NO. EPRO 
PRDCESSO 



00000 
00000 



00000 1 
00000 1 
00000 1 
00000 1 
00000 1 
00010 1 
00007 1 
00007 1 
00000 1 
00000 1 
00000 1 
00000 1 



00000 
00004 
00006 
00011 
00023 
00023 
00026 



00000 1 



SCONTROL U3LINIT 
BEGIN 

PEAL NUM:=1 ., 

DENOM:=0.» 
RESULT! 
INTEGER DUMMY1,DUMMY2; 

ARRAY DIVMSG(0:7):="DIVIDE OPERATION"; 
ARRAY ADDMSG(0:6):="ADD OPERATION "; 

PROCEDURE FDIVZROCQUOTTENT.TRAP) ; 
VALUE QUOTIENT, TRAP; 
REAL QUOTIENT; 
LOGICAL TRAP; 
BEGIN 
- If- QUPTIEWTS0. IHEN SO EX II; 
IF QUOTIENT<0, 

THEN QUOTIENT:=%37777777777D 
ELSE QU0TIENT:=%17777777777D; 
EXIT: 

RETURN 1; 
END; 



00000 1 

00000 1 

00000 1 

00000 1 

00000 1 

00005 1 

00010 1 

00010 1 

00014 1 

00020 1 

00020 1 

00024 1 

00030 1 
DB STORA 
RS=000; 
R TlHE=o:oo:02; 



INTRINSIC XARITPAP, PRINT, QUIT: 
<<END OF DECLARATIONS>> 



END. 
GE=%012; 



XARITRA.Pt %1 , eF&IVZRO, DUMMY 1 , DUMMY2) J 
IF < THEN QUITCl); 

PPINT(DIVMSG,8,0); 
PESULTs»!«im/DEROM; 

PRINT(ADDMSC,,7,0); 

:::RE:SUt;*Vsl«ESBi*iiE;sULT ; 

SECONDARY DB STORAGE=%00017 
NO. WARNINGS=000 
ELAPSED TIME=0:OO:ll 



X«i,.Eft : Vi:-g»C.H : ANGED>> C 
<<CHECK SIGN OF ANSWER>> 
<< - LARGEST VALUE>> 
<< + LARGEST VALUE>> 

«DELETE TRAP PARM ONLY>> 



«ARM FP/O, TRAP» 
<<CHECK FOP ERROP>> 

<<DIVIDE HFADING>> 
«DIVI0E» 

<<ADD HEADING>> 
«ADD» 



Figure 4-11. Using the XARITRAP Intrinsic 



Q-6 
Q-4 

Q 

S 



User 
Program 



RESULT 



Hardware Trap 

Type Parameter 

(%1) 



Stack Marker 



Arithmetic Trap 



The value of RESULT has been left at Q-6 and the FDIVZRO procedure uses this for QUOTIENT. 
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If QUOTIENT = (0 divided by 0), no action is taken and the procedure is exited, transferring 
control back to the user program. 

If QUOTIENT is less than 0, then the largest possible negative value is assigned to QUOTIENT. 
If QUOTIENT is not less than 0, the largest possible positive value is assigned. 
The statement 
RETURN 1; 

deletes only one word from the stack (the TRAP parameter at Q - 4) and returns to the program 
leaving the address of QUOTIENT (whose value is either %37777777777D or %17777777777D) at 
stack location Q - 5. 

When the statement 

RESULT:=RESULT+RESULT; 

tries to add the large value contained in RESULT to itself, the floating point overflow hardware 
trap aborts the process. The floating point overflow error was deliberately caused in this example 
program by assigning one of two largest possible values to RESULT and then attempting an add 
(RESULT + RESULT) which could not succeed. In a practical program, of course, such trap 
recovery (causing another intentional error) would not be used. The result of running the example 
program is shown below. 

; run ATRAP 

DIVIDE OPERATION 
ADD OPERATION 

ABORT :ATRAP. PUB, SUPPORT. %0.%26 

PROGRAM ERROR #3: FLOATING POINT OVERFLOW 

PROGRAM TERMINATED IN AN ERROR STATE, (CIERR 976) 



LIBRARY TRAP 

The software library trap reacts to major errors that occur during execution of procedures from the 
System Library. When a user program begins execution, this trap is disabled automatically. You can 
enable (or disable) it with the XLIBTRAP intrinsic. When enabled, the library trap passes control to 
a trap procedure in the event of an error. This procedure, in turn, returns to the user program four 
words containing the stack marker created when the library procedure was called by the user 
program. In addition, the trap procedure returns an integer representing the error number. When the 
procedure is completed, it either transfers control to the instruction following that which caused 
the error or aborts the process at your option. The trap procedure is defined by you, but it must 
conform to the special format discussed in the HP 3000 Compiler Library Manual. 
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The XLiBTRAP intrinsic call could be as follows: 

XLIBTRAP(PLABEL,OLDPLABEL); 

where PLABEL is the external-type label of your trap procedure. If the value of this parameter is 0, 
the trap is disabled. OLDLABEL is a word in which the previous plabel is returned to the use 
program. If no plabel existed previously, is returned. 

When a library trap procedure is invoked, the condition of the stack is: 



usuius'rAun. 



ERRORCODE 



ABORTFLAG 



SYSTEM TRAP 





USER'S PROGRAM 


Q'-3 




Q'-2 




Q'-l 




Q' 






COMPILER 
LIBRARY 
ROUTINES 


Q-6 


USERSTACK 


Q-5 


ERRORCODE 


Q-4 


ABORTFLAG 




USER'S TRAP PROCEDURE 



A woru pointer tu uie uoae ui uie ouawiv. iiuub.ci pai/wi un mc ■««"'" 

when the user program called the compiler library. 

A reference parameter indicating the type of compiler library error, 
described in the HP 3000 Compiler Library Manual. 

A reference parameter set before the user exits from the trap pro- 
cedure. If TRUE, the compiler library aborts the program with the 
standard error message (just as if no trap procedure had been executed). 
If FALSE, the compiler library does not abort the program and no 
error message is printed, in this case, the compiler library attempts 
error -recovery. 



I 
I 



The software system trap reacts to errors occurring in intrinsics called by user programs. Typical 
errors are 



DEC 1981 
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• Illegal access. An attempt by a user to access an intrinsic for which he does not have 
access capability. 

• Illegal parameters. The passing to an intrinsic of parameters that are not defined for the 
user's environment. 

• Illegal environment. The DB register is not currently pointing to the user's stack area. 

• Resource violation. The resource requested by a user is either illegal or outside the 
constraints imposed by MPE. 

When a user program begins execution, the system trap is disabled automatically. When enabled by 
the XSYSTRAP intrinsic call and subsequently activated by an error, the trap transfers control to a 
trap procedure. 

The system trap is enabled or disabled by a XSYSTRAP intrinsic call, as follows: 

XS YSTR AP(PLABEL,OLDPLABEL) ; 

where PLABEL is the external-type label of your trap procedure. If the value of this parameter is 0, 
the software trap is disabled. OLDPLABEL is a word to which the previous plabel is returned to 
your program. If no plabel existed previously, is returned. 

When a system trap procedure is executed because of an abort condition arising in a system 
intrinsic, the stack is readjusted to provide an eight- word parameter group between the intrinsic 
parameters and the stack marker. 



N WORDS 

Q-11 
Q-10 

Q-9 

Q-8 

Q-7 

Q-6 

Q-5 

Q-4 

Q-3 

Q-2 

Q-1 

Q 



USER PROGRAM 


N WORDS FOR THE 
CALLABLE INTRINSIC 


PARAMETER 1 


PARAMETER 2 


PARAMETER 3 


PARAMETER 4 


PARAMETER 5 


PARAMETER 6 


PARAMETER 7 


PARAMETER 8 




STACK MARKER 






SYSTEM TRAP PROCEDURE 





EIGHT-WORD 
PARAMETER GROUP 
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The format of the eight-word parameter group in Q-4 through Q-ll is 



BITS 



9 10 



15 



Q-11 


i 


N 


Q-10 


P 


Q-9 


P-1 


E-1 


Q-8 


P-2 


E-2 


Q-7 


P-3 


E-3 




Q-6 


P-4 


E-4 


Q-5 


P-5 


E-5 


Q-4 


P.e 


E-6 



PARAMETER 2 
PARAMETER 3 
PARAMETER 4 
PARAMETER 5 
PARAMETER 6 
PARAMETER? 
PARAMETER 8 



7 8 



I 

N 



P-1 through P-6 
E-1 through E-6 



Intrinsic number. 

Number of callable intrinsic parameters. (To resume execution in the 
user code domain, an EXIT N+8 instruction should be executed.) 

Additional parameter information. 

Parameters modifying the error bytes, described below. If no modifying 
parameter is present, the corresponding parameter byte is set to zero. 

Error bytes, containing the error codes noted in Section X. The last 
error code present is delimited by the value of zero in the following 
error byte. 



With these parameters, the trap procedure may tane any recovery action necessary— wri^e 
messages, produce selective dumps, set error-indication flags, or allow interactive debugging. Finally, 
the procedure may either call the TERMINATE intrinsic or issue an (EXIT N+8) instruction to 
return to the user program (at the location following that where the trap was invoked), with 
appropriate error indications. 

A sample declaration for a system trap procedure, and an example of how you might issue an EXIT 
N+8 instruction follow: 



PROCEDURE 



SYSTEMTRAP (PARAMETER 1, PAR AMETER2,PARAMETER3, 
PARAMETER4,PARAMETER5,PARAMETER6, 
PARAMETER 7,PARAMETER8); 
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VALUE 



LOGICAL 



BEGIN 



PARAMETER1,PARAMETER2,PARAMETER3,PARAMETER4, 
PARAMETER5,PARAMETER6,PARAMETER7,PARAMETER8; 

PARAMETER1,PARAMETER2,PARAMETER3,PARAMETER4, 
PARAMETER5,PARAMETER6,PARAMETER7,PARAMETER8; 



INTEGER N; 



< < USER MA Y OUTPUT MESSAGES > > 



N:=PARAMETER1 LAND%37; < < N=NUMBER OF PARAMETERS 

PASSED TO CALLABLE 
INTRINSIC > > 



TOS:=N+7o31410; 



ASSEMBLE (XEQ 0); 



< < PUT "EXITN+8" ON TOP 

OF STACK > > 

< < EXECUTE "EXIT N+8 " ON 

TOP OF STACK >> 



END; 



CONTROL-Y TRAPS 



If you are running a program in an interactive session, you can enable a special trap that transfers 
control from the currently-executing program to a trap procedure whenever a CONTROL-Y 
subsystem break signal is entered from the terminal. On most terminals, the CONTROL-Y signal is 
transmitted by pressing the Y key while holding the CONTROL key down. 

When more than one process is currently running within your process' tree structure, the 
CONTROL-Y signal interrupts the last process to enable the trap. 

When a process is interrupted by a CONTROL-Y signal, the following occurs: 

1. The input/output transactions pending between the process and the terminal are halted 
and flagged as though all were completed successfully. 

2. Control is transferred to the trap procedure defined by you, with which you can now 
interact. The trap procedure executes in the same mode (privileged or non-privileged) as 
the user program that was interrupted. 

3. Control returns from the trap procedure to the interrupted program or procedure. If the 
interrupted program or procedure was awaiting completion of input/output (reading from 
or writing to the terminal) when the CONTROL-Y signal was received, the FREAD or 
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FWRITE intrinsic that was executed is flagged as successfully completed when control 
returns from the trap procedure. If the CONTROL-Y signal was received during reading, 
the number of characters typed in before this signal is returned to you as the value of 
FREAD. The carriage position is unchanged. 

If you send another CONTROL-Y signal, it is ignored unless a call to the RE8ETCONTROL intrin- 
sic was issued at some point prior to the signal. 

If you send a CONTROL-Y signal while MPE system code is executing on your behalf, MPE searches 
back to the last user stack marker and sets bit of relative P in that marker. No interrupt will occur 
until an EXIT instruction is executed through the above marker. The trap is recognized, a marker is 
built, and control is transferred to the trap procedure. When the trap procedure is invoked, the 
condition of the stack is as follows: 





USER PROGRAM 
DATA 


Q-3 




Q-2 


RELATIVE P 


Q-1 








Q *" 


Q+1 




n 






S w 




CONT 

TRAP PR 

DA 


ROL-Y 

3CEDURE 

TA 



> USER STACK MARKER 



When the first instruction in the trap procedure is executed, the Q register points to the user stack 
marker and the S register points to Q+2. The trap procedure should not write data in the rightmost 
byte of the word Q+1, because this word contains the number of words in the stack, plus the stack 
marker. This value will be deleted from the stack upon exit from the procedure. This value is non- 
zero when parameters to a system procedure (which was executing when the CONTROL-Y occurred) 
have been left on the stack. On return, the trap procedure must know the value contained in Q+1 
and pass it to the N parameter of the EXIT N instruction. The EXIT N instruction must be placed 
on the stack as follows: 

TOS:=%31400+N; 

The Exit N instruction then is executed by an XEQ instruction. 
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NOTE 

If you are a user with the Privileged Mode Capability, you 
should be aware of the following: 

1. If your interrupted code was executing in privileged 
mode, your trap procedure also must be executed in 
privileged mode, and therefore must have privileged 
mode capability. 

2. When your process is executing in privileged mode, and 
a CONTROL-Y signal invokes a trap procedure, the trap 
procedure is entered with the same DB register setting in 
effect when the signal was received. Thus, if the DB 
register is pointing to an extra data segment rather than 
the user stack when a CONTROL-Y signal is received, it 
will continue to point to that extra data segment when 
the trap procedure is entered. 

Figure 4-12 shows a program containing a CONTROL-Y trap procedure. The statements 

LOOP: 

CNTR:=CNTR+1D; 

IF CNTR < 3000000D THEN GO LOOP; 

increment a double-word counter by ID each time the loop is executed. When the counter reaches 
the value 3000000D, program execution terminates. 

The CONTROL-Y trap procedure, beginning with the statement 

PROCEDURE CONTROLY; 

assumes control whenever CONTROL-Y is entered from the terminal. The trap procedure executes, 
then control passes back to the loop. 

The statement 

INTEGER SDEC = Q + 1; 

equivalences SDEC to Q + 1. The rightmost byte of Q + 1 contains the number of words on the 
stack to be deleted when the exit instruction executes. This value is passed to EXIT as the N 
parameter. 

The counter value is converted to an ASCII string by calling the DASCII intrinsic and the PRINT 
intrinsic call displays this ASCII string on the terminal. 

The RESETCONTROL intrinsic call enables the CONTROL-Y trap. To take effect, this intrinsic 
must be called from within the trap procedure. An EXIT instruction must be built and the 
statement 

TOS:=%31400 + SDEC; 
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SCONTPOL USLINIT 
BEGIN 

ARRAY HEADING(OslO) :="CONTROL Y TPAP EXAMPLE"; 

ARRAY MSGC0:15):="COUNTEP CUPPENTLY = ": 

BYTE ARRAY BMSGC»)=M5G; 

DOUBLE CNTR:=OD; 

INTEGEP DUMMY, LGTH; 

INTRINSIC PRINT,XcnNTRAP,OUIT,DASCII,RESETCONTROL; 
PRttCKBUM .CWtROLtiS- 

lattices sokcsq+u 

i,gt - : = p a 3C 1 1 1 c r. i v , ', f. , r " s-- <:><■) ; < « ' >n vk 'jt f. :h;m rv * > 



ppisT(«SG>lft f c>; 

HFSFTfTM.-f L ! 
TQSS =%31 400 +SDEC; 

«END OF DECLARATIONS>> 



«vtAi.h c-'KT?ni. j 7w?/^> 
*.F->Tcnr exit» 



<<PROGPAM ID>> 

«ARM CONTROL Y TRAP>> 

<<CHECK FOR EPR0R>> 



llllllllllllilllllllll 



PRIMARY DB STORAGE 
NO. EPRORS=000; 
PROCESSOR TIMK=0:0 



PRINTCHEADING,11,0)? 
XCONTPAPOCONTROLY, DUMMY) ; 
IF < THEN OUIT(l); 

CfcTR^sCKTR+SfJ; 
IS' CJSTR<}QOGO&0» THE» -Si? LOOP; <-*\X-MT I Jfl !Ot*.,~ L0t>P» 
END. 
r%007? SECONDARY DB STOPAGE=%00033 

NO. WARNINGS=000 
0:02; ELAPSED TIME=0!00:2fe 



Figure 4-12. Using the XCONTRAP Intrinsic 

accomplishes this, loading the octal value %31400 plus the value of SDEC (Q + 1) onto the top of 
the stack. The statement 

ASSEMBLE(XEQ 0); 

executes the statement on the top of the stack, which in this case is the EXIT instruction placed 
there by the previous statement. 

The CONTROL- Y trap is enabled by the statement 

XCONTRAP(@CONTROLY,DUMMY); 

The @CONTROLY parameter informs the system that a procedure (CONTROLY) is being passed as 
a parameter. 
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The results of executing the program are shown below: 

:RUN CONTY 



CONTROL Y TRAP EXAMPLE 

COUNTER CURRENTLY = 125153^ 

COUNTER CURRENTLY = 1093423* 

COUNTER CURRENTLY = 1860 957* 

COUNTER CURRENTLY = 2700949* 




CONTROL-Y 

ENTERED FROM TERMINAL 



END CF PROGRAM 



TIME AND DATE INTRINSICS 

You can programmatically request the return of system timer information with the TIMER intrinsic; 
the time of day with the CLOCK intrinsic; the calendar date with the CALENDAR intrinsic; and 
the duration, in milliseconds, that a process has been running with the PROCTIME intrinsic. 

OBTAINING SYSTEM TIMER INFORMATION 

A 31-bit logical quantity representing the current system timer count can be returned to your 
program with the TIMER intrinsic. This information can be used in routines that generate random 
numbers, or in measuring the real time elapsed between two events. The resolution of the system 
timer is one millisecond, thus readings taken within a one-millisecond period may be identical. 

This quantity is reset to zero on 24 day intervals at 12 o'clock midnight. Detection and correction 
of this case between two calls to TIMER (less than 24 days apart) for computing an elapsed time 
interval can be done as follows : 

If, when subtracting a current TIMER count from a previous count, the result is negative, 
add 2,073,600,000 (the number of milliseconds in 24 days) to the result. 

Figure 4-13 contains a program that uses the system timer bit count to generate a random octal 
number. This number then is converted to one of the ASCII characters ;,<,=, >,?,@,or A 
through Z. 

The statement 

CBUF(5):=INTEGER(TIMER).(ll:5)+%73; 

calls the TIMER intrinsic to obtain the timer count. A double-word quantity is returned as follows: 

BITS 1 WORD 2 15 WORD 1 15 



NOT USED 
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00021 1 
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00 032 1 
00035 1 
00035 1 
00O41 1 
00044 1 
00050 1 
H005 3 1 
00052 1 
6 7 1 
0O072 1 
1 1 1 
10 2 1 
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00110 2 
O0120 2 
012 1 
00126 1 
00 126 
00134 
10 141 



2 
2 
2 
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U0157 1 
00 162 1 
00171 1 
00177 1 
00202 1 
0202 1 
(10207 1 
00212 I 
On 220 1 
00??4 1 
00232 1 
nw STORA 

ors=ioo; 

OR TI«F=0 



SCONTKOl USLINIT 
BE GIN 

aYTE ARRAY INNAME(0:5) !="INPUT "J 

BYTE ARRAY OUTNAMF < : 6) : ="OUTP JT »* 

INTEGER IN, OUT, LGTH, DUMMY, TIME, TIMEOUT: = 10! 

ARRAY riUFR(0!3) !=»TYPE X«,0! 

BYTF ARRAY CBUK (» ) = RUFH ; 

ARRAY IMST«MCTION5(0:34) :="REACTION TIMER: 
■•TYPE THE REQUESTED CHARACTER AS QUICKLY 

ARRAY MSG(0!24>:="TrtY AGAIN? ( Y/N) ", "WRONG 
%6412, "YOU'RE TOO SLOw!"; 

ARRAY RESPONbt(0:i6) S=»H£ACT10M TIME: 

HYTE ARRAY CRFSP ( « ) =RESPONSE ; 



»,*6412, 

AS YOU CAN. "? 

CHARACTER.", 

MILLISECONDS"! 



INTRINSIC FOPEN, FRE AD, FWRITE.FCONTROL, ASCI I, TIMER, (SUIT! 



<<ENI> OF DECLARATIONS'^ 

In:=fopfN(1nname»*45) ; 

IF < THEim QUIT (1) * 
ni)T:=FOPEN(OUTNAME,*>4]4«*] ) » 

IF < THFN OUI1 (2! I 

fy.Hl rt ((lUTs INSTRUCT TOMS ,35, ) ! 

IF < THEN UUIT (3) 5 



LOOP: 



NEXT! 



f Mi). 
(iE=*016; 

:00:03; 



FfONTROL (IN, 21, DUMMY) ; 

IF < THEN UU1T (4) 5 

FCONTROL ( IN, 4, TIMEOUT) ! 

IF < THEN QUIT (5) » 

fMWVt,u^ln%i F_R£TJW«>.n *5 *%rs% ■ 

F«PtTF(OUT,hUFR,3»%320M 
r jr < *) HpN QUIT (6) 5 
L«TH:=FPEAD(IN,BUFR(3) ,-1)5 
IF < THFN 
BEGIN 

FWRITE(0UT,MSS(16) ,9,0) ! 
IF < THEN ailIT(7) ELSE GO NEXT? 
ENDS 
IF CHUF (5) OCBUE (6) THEN 
HEGIN 

F WRITE (OUT,MSG(H) ,«,0) ; 
IF < THEN QUIT!*) ELSE GO NEXT) 
ENDS 
rtOVf RESPONSES) ! =" " : 

FC0^TR0L(lN,2?,TIME) S 
IF <> THEN 0UIT(9) ; 
ASCII (riMt*10,10,CRESP(15) ) ! 
F WRITE (OUT, RESPONSE, 17,0) S 

IF < THEN OUIT (10) » 

F WRITE (OUl , mSG»h«%320) * 

IF < THFN QUIT! 11) ' 

FRF.AD<IN,BUFR<3> ,-1) ! 

IF < THFN QUIT (12) J 

IF Cm)F(6)= ,, f» THEN GO LOO°S 

bECONnARY OH STORAGE=%00130 
NO. WARMMGS = 00n 
ELAPSED rlME = o:()0:10 



<<$STDIN>> 
<<CHECK FOR ERROR>> 
<<$STDLIST>> 
<<CHECK FOR ERROR>> 
<<USER DIRECTIONS>> 
<<CHECK FOR ERROR>> 

<<ENABLE TIMER READ>> 
<<CHECK FOR ERROR>> 
<<ENABLE TIMEOUT>> 
<<CHECK FOR ERPOP>> 
«:<fiE«E-HATF ft l , **K4:'* ff f;»» 
«f?ESUEST OSES IttPUT» 
«CHECK FOR ERROP>> 
<<READ CHARACTERS 
<<TIMEOUT OCCURRED>> 

<<TOO SLOrt MESSAGE>> 
<<CHECK FOR ERROP>> 

<<INCORRECT CHARACTER>> 

<<WRONG CHARACTER MESSAGE>> 
<<CHECK FOR ERROR>> 

<<RESET RESPONSE TIME>> 
<<READ INPUT TIME>> 
<<CHECK FOR ERROR>> 
<<CONVERT TIME>> 
<<REACTION TIME>> 
<<CHECK FOR ERROR>> 

^^rQMTiwijr T£ST?>> 
<<CHECK FOP ERROR>> 
<<GET Y/N ANSWER>> 
<<CHECK FOR ERROR>> 
<<Y-CONTINUE TEST>> 



Figure 4-13. Using the TIMER Intrinsic 
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The INTEGER function strips word 2 from this quantity, leaving a 16-bit integer value. The low- 
order five bits of course change value most rapidly, and these bits are used to obtain a decimal 
number from to 32. 

The octal codes for ASCII characters ;,<,=, >,?,@, and A through Z range from 000073 to 
000132, or decimal values 58 through 90 (a difference of 32 decimal). Thus, by adding %73 to the 
value obtained from the low-order five bits of the system timer information, one of the above 
ASCII characters is generated by the foregoing statement and assigned to the 6th (CBUF(5)) 
position of byte array CBUF. The FWRITE displays this character, and the string "TYPE" on the 
terminal (CBUF and BUFR have been equivalenced, see statements 6 and 7). 

OBTAINING THE CURRENT TIME 

The CLOCK intrinsic returns the actual time (wall time) as a double word. The first word contains 
the hour of the day and the minute of the hour, the second word contains seconds and tenths of 
seconds, as follows: 

BITS 7 8 15 



HOUR OF DAY 



SECONDS 



MINUTE OF HOUR 



TENTHS OF SECONDS 



WORD1 
WORD 2 



In the following intrinsic call, the above information would be returned to the double-word iden- 
tifier TIME. 

TIME := CLOCK; 
OBTAINING THE CALENDAR DATE 

The CALENDAR intrinsic returns a logical value representing the year and day as follows: 
BITS 6 7 15 



YEAR OF CENTURY 



DAY OF YEAR 



In the following intrinsic call, the day and year information would be returned to the logical iden- 
tifier DATE. 

DATE -CALENDAR; 
OBTAINING PROCESS RUN TIME (USE OF THE CENTRAL PROCESSOR) 

The PROCTIME intrinsic returns a double integer value representing the duration, in milliseconds, 
that a process has been running (CPU time). 

In the intrinsic call shown below, the process run time would be returned to TIME. 
TIME := PROCTIME; 
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FORMATTING CALENDAR DATE AND TIME INFORMATION 

You can format the calendar date with the FMTCALENDAR intrinsic, the time of day with the 
FMTCLOCK intrinsic, and the calendar date and time of day with the FMTDATE intrinsic. These 
intrinsics use the information returned by the CALENDAR and CLOCK intrinsics. 

The simple program shown in Figure 4-14 illustrates the use of these intrinsics. 



$C0NTR0L USLINIT 
BEGIN 

BYTE ARRAY FMTDATE(Ol 16) > 
BYTE ARRAY FMTTIME(0l7) } 
BYTE ARRAY DATETIME(0s26) } 

ARRAY FMT*DATE(*)*FMTDATEj 
ARRAY FMT'TIME(*)*FMTTIME» 
ARRAY DATE*TIME{*)*DATETIME> 

LOGICAL DATE? 

DOUBLE TIME? 

INTRINSIC CALENDAR, CLOCK, FMTCALENDAR, FMTCLOCK, FMTDATE, PRINT; 

DATE:*CALENDAR» 
TIME!=CLOCK; 

FMTCALENDAR(DATE,FMDATE) J 
PRINTCFMT'DATEf-n^eO) J 

FMTCLOCK(TIME,FMTTIME) » 
PRINT(FMT'TIME,-8,%60)> 

FMTDATE(DATE # TIME,DATETIME) > 
PRINT(DATE'TIME,-27,0)> 

END. 



Figure 4-14. FMTCALENDAR, FMTCLOCK, and FMTDATE Intrinsics Example 



4-45 



INTERPROCESS COMMUNICATION 

You can arrange for two processes belonging to the same job/session to communicate with each 
other through a job control word (JCW). This word is used by systems programmers to enable a 
subsystem process to return information to the command executor that initiated that process. Such 
a communication mechanism is used by the command executors for :RUN and various subsystem 
commands. However, you may find this control word helpful in other applications. 

The SET JCW intrinsic is used to set the bits in the job control word (JCW). A SETJCW intrinsic call 
could be 

SETJCW(WORD); 

where WORD is a 16-bit logical word whose bits are set by you. If you set bit to 1, the system dis- 
plays the following message when your program terminates, either normally or due to an error: 

PROGRAM TERMINATED IN AN ERROR STATE (CIERR 976) 

Bits 1 through 15 may be set to any pattern. 

NOTE 

In batch mode, the job is terminated unless the :CONTINUE 
command is used. If you have a JCW of exactly %14000, 
(bits and 1 only), the CIERR 976 message is replaced by 
CIERR 989, PROGRAM ABORTED PER USER REQUEST. 
See the MPE Commands Reference Manual for a discussion 
of : CONTINUE. 

The job control word (JCW) can be read by a process with the GET JCW intrinsic. The form of the 
GET JCW intrinsic call is 

JCW : = GET JCW; 

The job control word would be returned to JCW in the above intrinsic call. 

As an example, consider a job where two processes pass information to each other through the job 
control word. In one process, you transmit the contents of the word PROCLNK to the job control 
word. Process A sets the job control word to PROCLNK as follows: 

SETJCW (PROCLNK); 

When process B is executed, it obtains this current job control word through the GETJCW intrinsic. 
In this case, the contents of the job control word are returned to the word STORELNK. 

STORELNK: =GETJCW ; 
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USER-DEFINED JOB CONTROL WORDS 

MPE allows you to establish and manipulate job control words including the system-defined job 
control word "JCW." This capability overcomes a disadvantage of using the system-defined JCW, 
which is that because MPE uses the JCW for status information, you cannot be sure that MPE will 
not modify it, thus destroying whatever information you may wish to pass. 

A user-defined JCW is a 16-bit logical word which resides in an MPE managed table. This table, 
which also holds the system-defined JCW, is shared by all processes in a job, thus any process of a 
job can access any JCW in the table. 

The name of a user-defined JCW must start with a letter and be between 1 and 255 characters long. 

A user-defined JCW is established with the PUTJCW intrinsic. This intrinsic scans the JCW table for 
a given JCW. If found, the JCW's value is updated to the value passed by the PUTJCW intrinsic call. 
If a JCW of that time is not found, the name is added to the table and assigned the value passed 
with the name. For example, the intrinsic call 

PUTJCW (JCWNAME,JCWVALUE,STATUS) ; 

would search the JCW table for a name which matches the name contained in JCWNAME (a byte 
array). If the name exists, its value is updated to the value contained in JCW VALUE. If a name 
matching that contained in JCWNAME is not found, the name is added to the JCW table and 
assigned the value contained in JCW VALUE. 

The STATUS parameter indicates the status of the intrinsic call and returns an integer value to 
indicate this status as follows: 

- Successful execution. 

1 - Error. JCWNAME is longer than 255 characters. 

2 - Error. JCWNAME does not start with a letter. 

3 - Error. The JCW table is out of space. 

The FINDJCW intrinsic is used to scan the JCW table for a given JCW name and return its value. 



Thus, the intrinsic can 

FINDJCW(JCWNAME,JCWVALUE,STATUS); 

would search the JCW table for a JCW of the same name as that contained in JCWNAME. If a JCW 
of the same name is found, its current value is returned in JCWVALUE. If a JCW of the same name 
is not found, an error is returned in STATUS. 

The STATUS parameter indicates the status of the intrinsic call and returns an integer value indicat- 
ing this status as follows: 

- Successful execution. 

1 - Error. JCWNAME is longer than 255 characters. 

2 - Error. JCWNAME does not start with a letter. 

3 - Error. The JCW named in JCWNAME does not exist. 
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MPE MESSAGE SYSTEM 

The MPE message system consists of a message catalog (CATALOG.PUB.SYS), the Help subsystem 
catalog (CICAT, containing descriptions of all MPE commands), any number of user message cata- 
logs, a program (MAKECAT) for building message catalogs, and an intrinsic (GENMESSAGE) used 
to insert parameters in messages in a catalog. 

MESSAGE CATALOG 

A message catalog must be a standard editor-type file containing sets of messages. That is, a num- 
bered file which contains 80 byte records in a fixed record format. The sets serve to break a catalog 
into manageable portions. After a message file is created, the MAKECAT program is used to build a 
catalog that is readable by the message system. This catalog file can still be texted into the editor, 
but it now contains a directory (written as a user label by MAKECAT). 

Messages in the catalog can be of any length and can contain up to five parameters (parameters are 
indicated in a message by the symbol !). Continuation of a message is indicated by "%" or "&" at 
the end of a line. The "%" symbol indicates that the message is continued and that a carriage return, 
line feed will be issued to the terminal. The "&" symbol indicates that the message is continued on 
the same line with no carriage return, line feed. The GENMESSAGE intrinsic ignores all blanks 
between the last non-blank character of a message and the continuation character. This allows 
free-formatting of the continuation character. 

Message sets are indicated by "$SET n" starting in column 1 (the rest of the line is treated as a 
comment). Maximum value for n is 62. Comments can be inserted in the catalog by placing "$" in 
column 1 of a line. Message numbers are positive integers, need not be contiguous, but must be in 
ascending order. After processing by the program MAKECAT, the catalog file contains records of 
80 bytes, blocked 16, in 32 extents. (The system message catalog is only one extent, however.) 

The format of the message catalog is as follows : 

$SET 1 SYSTEM MESSAGES 

1 LDEV #! IN USE BY FILE SYSTEM 

2 LDEV #! IN USE BY DIAGNOSTICS 

3 LDEV IN USE, DOWN PENDING 
5 IS"!"ONLDEV#! (Y/N)? 



$ MESSAGE 35 IS TWO LINES LONG, A PARAMETER STARTS THE 
$ FIRST LINE AND THE SECOND LINE IS "HP32002" 
35!% 
HP32002B.00. ! 



276 LDEV # FOR "!" ON ! (NUM) ! 
$ 

$SET 2 CIERROR MESSAGES 

82 STREAM FACILITY NOT ENABLED: SEE OPERATOR. (CIERR 82) 
200 MORE THAN 30 PARAMETERS TO BUILD COMMAND. (CIERR 200) 
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204 FILE COMMAND REQUIRES AT LEAST TWO PARAMETERS, INCLUDING THE % 
FORMAL NAME OF THE FILE. (CIERR 204) 



MAKECAT PROGRAM 

The program MAKECAT.PUB.SYS is used to build message catalogs (and Help catalogs). The pro- 
gram's input file has the formal designator INPUT. The program has the following entry points: 



No entry point 



BUILD 



DIR 



HELP 



Reads from input file and builds a temporary file (formal designator 
CATALOG). Also renames any old temporary CATALOG, CATnn, 
using an archival numbering scheme (i.e., CAT1, CAT2, etc.). 

(Must log on under MANAGER.SYS to use this entry point.) Reads 
from input file, builds the system message catalog (formal designator 
CATALOG), and installs the message system. Existing catalog is re- 
named CATnn according to the same scheme as for no entry point 
(above). Installation of the message system means moving the directory 
contained in the user label of the catalog into a data segment. The Data 
Segment Table (DST) number and the disc address of CATALOG are 
placed in the system global area. The message system may be installed 
while the system is running. 

(Must log on under MANAGER.SYS to use this entry point.) Installs 
the system message catalog (does not build a new one). Opens input 
file, moves the directory in the CATALOG into a data segment, and 
places the DST number and disc address of CATALOG in the system 
global area. This entry point may be used when the message system 
seems to be malfunctioning, but the catalog is intact. (For example, 
MPE is issuing "MISSING MSG SET=mm. MSG=nn" at terminals and 
the system console.) This may be done while the system is running. 

(Must have System Manager of System Supervisor capability to use this 
entry point.) Used to build the Help catalog. Reads input file and builds 
a Help catalog (formal designator HELPCAT). 



EXAMPLES. To use MAKECAT to build your own message catalog, enter: 

:FILE INPUT=CAT15 

:RUN MAKECAT .PUB.SYS 

** VALID MESSAGE CATALOG (printed if no errors in catalog CAT15) 

:SAVE CATALOG 
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To use MAKECAT to modify the system message catalog: 

1. Text CATALOG.PUB.SYS into the Editor. 

2. Make the desired changes. 

3. Keep the file under a new name and exit the Editor. 

4. LogonasMANAGER.SYS,andenter: 

:FILE INPUT=catname.group.account 

:RUN MAKECAT ,BUILD 

** NEW CATALOG INSTALLED 

To reinstall the message catalog if MPE is printing "MISSING MSG. SET=mm. MSG=nn," enter: 

HELLO MANAGER.SYS 
FILE INPUT = CATALOG 
RUN MAKECAT,DIR 
** NEW CATALOG INSTALLED 

To build a Help catalog for the command interpreter, enter: 

:HELLO MANAGER.SYS 
PURGE CICAT 

FILE INPUT =catalog.group .account 
RUN MAKECAT ,HELP 
END OF PROGRAM 
: RENAME HELPCAT, CICAT 

USING THE GENMESSAGE INTRINSIC TO INSERT PARAMETERS IN MESSAGES 

The GENMESSAGE intrinsic can be used to access the MPE message system. GENMESSAGE is 
called with a message number from a catalog as a parameter. The message system fetches the mes- 
sage from a message catalog, inserts parameters, then routes the message to a file or returns the 
message in a buffer to the calling program. 

In order to use the message catalog, the program must first open the message catalog, then call 
GENMESSAGE with the file number, message set number, and message number. The file must be 
opened with the aoptions nobuf and multi-record access. 

NOTE 

The file must be opened with f options old, permanent, 
ASCII (foptions 5), and aoptions nobuf and multi-record 
access (aoptions %420). 

Parameters may be inserted into the message from the catalog. The parameters are passed to the 
message with the parml, parm2, parm3, parm4, and parm5 parameters in the GENMESSAGE 
intrinsic call and are inserted in the message wherever a "!" is found. Parameters are inserted in the 
following order: parml substitutes for the leftmost "!" in the message, parm2 for the next leftmost, 
and so forth. If parm(n) is present, parm(n-l) must be present (for example, you cannot specify 
parm3 unless parml and parm2 are specified). 
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Figure 4-15 contains a simple program that inserts the value 95 into message number 11 in message 
set 1 in the message catalog CATALOG. PUB. SYS. The complete message then is displayed on the 
terminal. Note that the file CATALOG .PUB .SYS is equated to CATALOG with a :FILE command, 
then the name CATALOG is used in the FOPEN call (passed to FOPEN in byte array BUFF). Note 
also that the file is opened with aoptions nobuf and multi-record access (aoptions %420). The 
message set (1) and message number (11) are included as parameters in the GENMESSAGE call. 
The parameter parmask is set to %10000 and parml (NUMBER) has the value 95. The complete 
message is returned in BUFF, which is then printed on the terminal with the PRINT intrinsic. 



fSPLPREP TEST.MSGTFST 

PAGE 0001 FPJ2100A.06.4J [4W] CO HEWLETT-PACKARD COMPANY 1976 

00001000 00000 SC0NTP0L USLINIT 

00002000 00000 BEGIN 

00003000 00000 1 

00004000 00000 1 BYTE ARRAY BUFF(0:255); 

00005000 00000 1 ARRAY 0UTBUFF(*)=BUFF ; 

00006000 00000 1 

00007000 00000 1 INTEGER FILENUM, MSGLEN, NUMBER:=95 } 

00008000 00000 1 _ „„_ 

00009000 00000 1 INTRINSIC FOPEN, PRINTFILEINFO, GENMESSAGE, PRINTS 

00010000 00000 ! 

00012000 00016 1 FILFNUM:=FOPENCBUFF,5,%420) J 
00013000 00026 1 IF <> THEN PR1NTF1LEINF0CFILENUM) ; 

00014000 00031 1 ., „„„„ 

00015000 00031 J msGLEN:=GENMESSAGE(FILENUM. 1.11, BUFF, ,%10000, NUMBER) J 

00016000 00045 1 

00017000 00045 1 PR JNTfOUTBUFF, -MSGbEN, 0) ; 

00018000 00051 1 

00019000 0005! 1 END, 

PRIMARY DB STORAGE = %005 ', SECONDARY DB STC1RAGE = %00200 

NO, ERRORS=0000; NO. WARNINGS=0000 

PROCESSOR TIME-0:00:00; ELAPSED TIME=0:00:29 

END OK COMPILE 

END OF PREPARE 

:SAVE MSGTEST 

:FILE CATAL0G=CATAL0G.PUB.SYS 

:RUN MSGTEST 

LDEV*95 NOT READY 

END OF PR0GRA" 



Figure 4-15. GENMESSAGE Intrinsic Example 
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DEVICE CHARACTERISTICS 



SECTION 



MPE intrinsics can be used to alter certain aspects of device operation. Before any of these intrinsics 
can be issued against a device, however, the device file must be opened with the FOPEN intrinsic 
(see Section II, page 2-71). 

With the FCONTROL intrinsic, you can 

Change terminal speed. See page 5-10. 

Change input echo facility. See page 5-11. 

Enable and disable the system break function. See page 5-13. 

Enable and disable subsystem break requests. See page 5-14. 

Enable and disable parity checking. See page 5-14. 

Enable and disable tape-mode option. See page 5-15. 

Enable and disable the terminal timer. See page 5-15. 

Read the result from the terminal input timer. See page 5-18. 

Define line-termination characters for terminal input. See page 5-19. 

Control the operation of a primary reader/punch. See page 5-4. 

In addition, you can programmatically read paper tapes not containing the X-OFF control character 
with the PTAPE intrinsic. See page 5-20. 

DEVICE CHARACTERISTICS 

PAPER TAPE READER 

The paper tape reader driver is capable of reading tapes in either BINARY or ASCII format. The 
mode is determined by the ASCII/BINARY bit in the f options parameter of the FOPEN intrinsic. 
The default condition for this foption is ASCII; however, this default condition can be altered with 
the FCONTROL intrinsic (see page 2-49). 

BINARY MODE. In binary mode, the device will read the number of words/bytes requested 
without regard to any special characters present on the tape. Tape leaders are skipped automatically 
by the hardware. For example, whenever the roller is raised to load a new tape, the device sets an 

.-„x i jm„„ „.u;„u «„„c«c ;+ +^ Jrrnr>ro oil lAnHintr null characters on the next read. After this first 

read, the flag is reset. Thus, trailers and embedded nulls are as valid as any other characters. The full 

8-bit character is read, and characters are packed two characters per word. There is no defined 

end-of -record character in binary mode, so the read is terminated only when the word/byte count is 

satisfied. 

If a time-out occurs (for example, for a tape bind, broken tape, or an attempt to read beyond the 

end of the tape), an error (CCL) is returned to the calling program. 

a qr-TT unnu Tr, asptt mnHp t-.hp following conditions aDDlv by default: 
• Bit 8 (parity bit) is set to zero. 
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• The carriage-return character (%15) is recognized as the end-of-record character. In other 
words, data transfer stops when the word/byte count is satisfied or when the 
end-of-record character is detected. (However, if word/byte count is satisfied before the 
end-of-record character is found, the tape motion continues until end-of-record is 
detected, with the extra characters being ignored.) 

• Data characters are packed automatically with two characters per computer word. 

The following characters are not transferred as data and result in the following action: 

Carriage-return (%15) End-of-record. 

Line-feed (%12) Ignored. 

X-ON (%21) Ignored. 

X-OFF (%23) Ignored. 

Rub-out (%177) Ignored. 

Control H (%10) Previous character deleted from data buffer. 

Control X (%30) All data in current record are deleted. The tape 

is advanced to the next record and the read is 

restarted. 
Control Y (%31) Ignored. 

Null (% 0) Consecutive nulls are counted to determine 

end-of-tape. 

• Any number of leading null characters are allowed. However, after the first non-zero 
character in a record, 20 consecutive null characters are treated as the end-of-tape 
condition and result in the following actions: 

a. Tape motion is stopped. 

b. Any characters already read are deleted. 

c. The message 

LDEV #nn NOT READY 

is output to the system console. The operator should insert the next tape to be read 
into the paper tape reader. 

d. When the READY interrupt is detected, the READ request is restarted and 
operation continues as before. 

The entire sequence is invisible to the calling program, except for the delay required to change 
tapes, so that multiple tapes may be read as if they were a single tape. 

NOTE 

There should always be at least one non-null character, such 
as a line feed, before the TRAILER to allow it to be 
distinguished from the LEADER. 
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All job control cards (i.e., : JOB, :DATA, :EOD, :EOJ, etc.) are recognized in the standard way to 
allow batch input from paper tape. 

PAPER TAPE PUNCH 

The paper tape punch driver is capable of punching tapes in either BINARY or ASCII format. The 
mode is determined by the ASCII/BINARY bit in the foptions parameter of the FOPEN intrinsic. 
The default condition of ASCII mode may be altered with the FCONTROL intrinsic. 

BINARY MODE. In BINARY mode, all characters are punched exactly as they appear in the 
buffer. No characters are deleted or added. Data characters are unpacked automatically, assuming 
two characters per computer word. In other words, no end-of -record marks such as carriage return 
are punched unless they are in the buffer. All bit patterns are considered valid and none have any 
significance as far as the driver is concerned. If you want end-of -record marks on the tape, you must 
provide them. Note, however, that the paper tape reader driver also attaches no significance to the 
end-of-record marks. 

ASCII MODE. In ASCII mode, the following conditions apply by default: 

• Trailing blank characters (%40) are not punched on the tape. This feature saves paper 
tape on short records, and also speeds up the net transfer rate for output and for input 
when the tape is read. 

• All other characters, including leading and embedded blanks, are transferred as data. No 
special characters are recognized. 

• A record termination sequence, consisting of X-OFF (%23), a carriage return (%15), 
followed by a line feed (%12), is appended to the end of each record. 

• Data characters are unpacked automatically, assuming two characters per computer word. 
CARD READER 

The card reader is a unit record device. The data is read in ASCII mode; that is, two columns are 
converted to ASCII and packed into the left and right byte of one word. If the read request 
specifies 80 or more bytes, 80 bytes will be transmitted independent of the data on the card. 

LINE PRINTER 

The line printer is a print and space device (postspace). The prespace operation is simulated by 
performing a print operation and then filling the line printer buffer. Note that a carriage control 
code of %320 will append data to the current contents of the line printer buffer, whether prespace 
or postspace is selected. 

Table 5-1 describes the differences between the 5 subtypes of line printers. 

The HP 2608/2610/2614 printers use a 6-bit space count that allows vertical spacing of up to 63 
lines when carriage control codes of %200 to %277 are used. 
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The HP 2607/2613/2617/2617J/2618/2619 printers have only a 4-bit space count that imposes a 
maximum vertical spacing of 15 lines at a time. MPE will simulate vertical spacing of more than 15 
lines, when carriage control codes of %200 to %277 are used, by concatenating as many 15-line 
spacings as necessary. The final spacing may consist of less than 15 lines. 



Table 5-1. Line Printer Differences 



SUBTYPE 


HP PRODUCT NO. 


SUPPRESS 
SPACE 


VFC CHANNELS 
AVAILABLE** 





2610 


YES 


1-8 





2614 


YES 


1-8 


1 


2607 


NO* 


1-8 


2 


2613 


YES 


1-12 


2 


2617 


YES 


1-12 


2 


2618 


YES 


1-12 


2 


2619 


YES 


1-12 


3 


2617J 


YES 


1-8 


4 


2608 


YES*** 


1-16 


A suppress space request (carriage control code = %53 or %200) will result in a single space without 
automatic page eject. 


Carriage control codes %300 to %31 7 specify VFC channels 1-16 respectively. A request to skip to 
a channel which is undefined for that subtype printer will result in a single space (with or without 
automatic page eject, the same as for carriage control code %10). 


Data may be lost if spacing is suppressed on two or more consecutive requests. 



To change the mode control settings (pre/post spacing and auto/no auto page eject) FWRITE is 
used with carriage controls %100 — %103 and %400 — %403. If FWRITE is called with one of 
these carriage controls and count=0 (count =1 if imbedded control), then no physical I/O will 
occur; the only effect is changing the mode. 



MAGNETIC TAPE 

The magnetic tape unit reads and writes variable length records in packed binary mode. Each word 
of data is represented by two tape characters. On read requests, the amount of data transferred is 
the lesser of the read request length and the tape record length. 

After write operations, when the end of tape reflective marker is detected, an EOT indication is 
returned. A request initiated before the EOT marker was detected is completed but an EOT 
indication is returned. 
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PRINTING READER/PUNCH 

The HP 30119A printing reader/punch is supported in three ways by MPE: 

1. As a card reader which, from a user program's viewpoint, behaves exactly like the 
HP 30106A/30107A card readers. This mode of operation prevails when the device is 
opened by device class name and the device class access type is input only. In this mode, 
default is select primary hopper and primary stacker. 

2. As a card punch. This mode of operation prevails when the device is opened by device 
class name and the device class access type is output only. In this mode, default is select 
secondary hopper and secondary stacker. 

3. As a printing reader/punch with two input hoppers and two output stackers over which 
the user has complete control. This mode of operation prevails when the device is opened 
by logical device number or by device class name when the device class access type is 
input/output. 



5-5 



In the mode of operation described under 3 above, you can control all aspects of the device with 
the intrinsic call 

FCONTROL(/ ilenum,0,param); 

where the bit settings of param signify the following: 

Bits (0:6) = Reserved for MPE. These bits should be set to zero. 

Bit (6:1) = 0. Select no inhibit feed on writes. 

= 1. Select inhibit feed on writes. 

Bit (7:1) = 0. Select punch on writes. 

= 1. Select no punch on writes. 

Bit (8:1) =0. Select print on writes. 

= 1. Select no print on writes. 

Bit (9:1) = 0. Select print and punch same data on writes. 

= 1. Select print and punch separate data on writes. 

Bit (10:1) = 0. Select primary stacker. 

= 1. Select secondary stacker. 

Bit (11:1) = 0. Select primary hopper. 

= 1. Select secondary hopper. 

Bits (12:4) = 'Reserved for MPE. These bits should be set to zero. 

When the device is opened for the first time, all of above parameter selections assume a default value 
of zero. Subsequent opens, however, do not necessarily yield these default values; the parameter 
selections for such opens assume the values established by previous opens. 

The FREAD and FWRITE intrinsics perform the following actions for the printing reader/punch. 



FREAD 



FWRITE 



a. 
b. 

c. 
d. 

e. 



a. 
b. 
c. 



d. 



Feeds a card from the hopper selected. 

Moves card from wait station (if present) to stacker last selected 

(no punch or print performed). 

Reads data from (a) and transfers it to caller's buffer. 

The mode (ASCII or column binary) of the read is specified on 

each read/write. 

The following parameter selections have no effect: 

same/separate print data; 

print/no print; 

punch/no punch; 

inhibit input feed. 

Moves card from the wait station to the stacker last selected. 
Prints and/or punches card (1) using data in caller's buffer. 
If inhibit input feed has been selected, no card is fed from 
hoppers. If inhibit feed has not been selected, card is fed from 
hopper last selected; any data on that card is lost. 
If separate print data has been selected, a double buffer is 
expected and punch data is extracted from the first part, print 
data from the second part. No print and no punch selections are 
still honored. If no print or no punch is on, a single length buffer 
suffices. If separate print data has not been selected, then the same 
data is printed and punched, unless no print or no punch has been 
selected. 
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e. The mode (ASCII or column binary) used will be the one last 
selected. 

f . If no print is selected, printing is inhibited. 

g. If no punch is selected, punching is inhibited. 

The FCONTROL param selections (bits 6 through 11) remain in effect until changed by another 
FCONTROL intrinsic call. 

LINE PRINTER AND TERMINAL CARRIAGE-CONTROL CODES 

Line printer and terminal carriage-control codes are shown in table 5-2. All of the carriage-control 
codes shown in table 5-2 may be used as the value of the param parameter of FCONTROL (when 
controlcode = 1) regardless of whether the file is opened with CCTL or NOCCTL specified in the 
FOPEN intrinsic. When the file is opened with CCTL, the carriage-control codes may be used in 
either of the following ways via FWRITE: 

1. As the value of the control parameter. 

2. When control = 1, as the first byte of the target array. 

Carriage-control codes greater than %403 cause an error return with no operation performed. 
The default mode controls are post spacing with automatic page eject. 
END-OF-FILE INDICATION 

An end-of-file indication is returned by the card reader and tape drivers under conditions specified 
by the initiators of read requests. The types of requests and the end-of-file classes are as follows: 



Type 



Class of end-of-flie 



A All records that begin with a colon ( :). 

B All records that contain, starting in the first byte, :EOD, :EOJ, :JOB 

and :DATA (See Note.) 

E Hardware-sensed end-of-file 

NOTE 

If the word count is less than 3 or the byte count is less than 
6, then Type B reads are converted to Type A reads. 

In utilizing the card/tape devices as files via the File System, the following types are assigned. 
File Specified T yP e 

$STDIN Type A. 

$STDINX Type B. 

Dev=CARD/TAPE Type B, if device accepts jobs or data. 

Type E, if device does not accept jobs or data. 
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Table 5-2. Carriage-Control Directives 



OCTAL CODE 



%40 
%53 

%55 
%60 
%61 



%2nn (nn is any 

octal number 

from through 

77) 
%300-%307 

%300-%313 

%300-%317 



%300 

%301 

%302 

%303 

%304 

%305 

%306 
%307 

%310 

%31 1 



ASCII SYMBOL 



"+" 



"0" 

it-ii ft 



CARRIAGE ACTION 



Single space (with or without automatic page eject). 

No space, return (next printing at column 1). Not valid on 2607 
(results in single space without automatic page eject). 

Triple space (with or without automatic page eject).* 
Double space (with or without automatic page eject).* 
Page eject (form feed). Selects VFC Channel 1. Ignored if: 
Post-space mode: The current request has a transfer count of 
and the previous request was an FOPEN or FCLOSE or an 
FWRITE which specified a carriage-control directive of %61. 
Pre-space mode: Both the current request and the previous re- 
quest have transfer counts of 0, and the current request and 
previous request are any combination of FOPEN, FLCOSE or an 
FWRITE specifying a carriage-control directive of %61 . 

Space nn lines (no automatic page eject). %200 not valid for 2607 
(results in single space without automatic page eject). 

Select VFC Channel 1-8 (2607) 

Select VFC Channel 1-12 (2613, 2617, 2618, 2619) 

Select VFC Channel 1-16 (2608) 

NOTE: Channel assignments shown below are the HP standard 
defaults. 

Skip to top of form (page eject). 

Skip to bottom of form. 

Single spacing with automatic page eject. 

Skip to next odd line with automatic page eject. 

Skip to next third line with automatic page eject. 

Skip to next 1/2 page. 

Skip to next 1/4 page. 

Skip to next 1/6 page. 

Skip to bottom of form. 

User option (2613/17/18/19), skip to one line before bottom of 
form (2608) 



•Note: 



Series 30/33/44: If these codes are selected with automatic page eject in effect (by default or following an Octal Code of %102 or 
A402I, the resulting skip is to a location absolute to the page. A code of %60 is replaced by %303 and %61 is replaced by %304 Thus 
the resulting skip may be less than two or three lines, respectively. 

If automatic page eject is not in effect, a true double or triple space results, but the perforation between pages is not automatically 
skipped. ' 

Series ll/lll: If these codes are selected with automatic page eject in effect, %60 and %61 are replaced by two or three %302 codes 
respectively. This results in true double or triple spacing, and also skips the perforation. 

If automatic page eject is not in effect, the behavior is the same as for Series 30/33/44. 
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Figure 2-3. Carriage-Control Directives 



OCTAL CODE 



ASCII SYMBOL 



CARRIAGE ACTION 



%312 

%313 
%314 
%315 
%316 
%31 7 
%320 
%2-%37 
%41-%52 
%54 

%56-%57 
%62-%77 
%104-%177 
%310-%317 (2607) 
%314-%317 (2613/17/18/19) 
%321-%377 
%400 or %100 



User option (2613/17/18/19), skip to one line before top of form 

(2608) 

User option (2613/17/18/19), skip to top of form (2608) 

Skip to next seventh line with automatic page eject. 

Skip to next sixth line with automatic page eject. 

Skip to next fifth line with automatic page eject. 

Skip to next fourth line with automatic page eject. 

No space, no return (next printing physically follows this). 



%401 


or 


%101 


%402 


or 


%102 


%403 


or 


%103 



Same as %40 



Sets post-space movement option; this first prints, then spaces. If 
previous option was pre-space movement, the driver outputs a 
line with a skip to VFC Channel 3 to clear the buffer. 

Sets pre-space movement option; this first spaces, then prints. 

Sets single-space option, with automatic page eject (60 tines per 

page). 

Sets single-space option, without automatic page eject (66 lines 

per page). 



Any subsequent requests to the driver after an end-of-file condition is senses, are rejected with an 
end-of-file indication. 

When reading from an unlabeled tape file, a request encountering a tape mark responds with an end- 
of-file indication but succeeding requests are allowed to continue reading data past the tape mark. 
Under these conditions, it is the responsibility of the caller to protect against the occurrence of data 
beyond an end-of-file and to prevent reading off the end of the reel. 

TERMINALS 

Terminals are supported by MPE through the terminal controller (each controller controls up to 16 
terminals). The terminal controller supports 103A and 202A modems, and hardwired terminals. 

™ RM TM4L TYPES- The terminals shown in Table 5-3 are supported by MPE. Terminals equipped 
with the automatic linefeed feature (operator selectable) must be operated with tins feature OFF. 
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SPECIAL KEYS. The following keys have special significance to MPE. 
ey Meaning 

X ° Deletes (ignores) the line being typed and then reads any following characters. 

The system responds with a triple exclamation point (!!!) followed by a carriage- 
return and linefeed. (The superscript c denotes a control character Thus "X c " 
means "CONTROL-X.") 

H ° Deletes the Previous character. (To delete n characters, enter n H c 's.) See note 

below. 

Q ° Places termin al in tape mode, allowing input from paper tape. When enabled, the 

tape-mode option inhibits the implicit linefeed normally issued by MPE each 
time a carriage return is entered. The tape-mode option also inhibits responses to 
H c and X c entries. Thus, when X c is received and tape mode is in effect no 
exclamation points (!!!) are sent to the terminal. If used after S c , Q c also 
resumes write operation during output (cancels S c ). 

Indicates the beginning of a block mode read and starts a special block mode 
timer. If the read doesn't complete successfully within the timer period (ap- 
proximately twice the expected read time determined from line speed and 
number of characters to read plus thirty seconds), the read is returned with an 
FSERR 27. Normal block mode transfers proceed as follows: The computer 
sends DC1 to the terminal to initiate a read. If the user has pressed ENTER for a 
block mode read, the terminal then sends DC2 (R c ) to the computer to indi- 
cate a block mode read; the computer sends another DC1 to the terminal to 
initiate the transfer; the terminal then sends the data to the computer. 

NOTE: R c has special significance only for termtypes which support block 
mode. 



R c 



S Suspends the write operation during output. 



Y c 



ESC: 



If the terminal is not in tape mode, Y« requests subsystem break (terminating 
program or command execution). If the terminal is in tape mode, Y c returns it 
to the keyboard mode. 



BREAK Requests a system break. 



Places the terminal in the echo-on mode so that characters input are echoed on 
the terminal by MPE. 



ESC; Places the terminal in echo-off mode so that characters input are not echoed on 

the terminal by MPE. 
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Key 



Meaning 



LINEFEED For any terminal with a linefeed entry, the log-on user may strike this key and a 

carriage return will be echoed. The linefeed character is not transmitted to the 
input buffer. This mechanism permits multiple lines to be entered in response to 
a single read request (for example, the length of a read request from a terminal is 
not constrained by the carriage or line width). 

The defined control characters Xc, He, Qc, Sc, and Yc are recognized even when following an ESC 
key entry. However, entry of ESC followed by any other character (other than one of these control 
characters, a colon, or a semicolon) is read as a 2-character string in the user's input stream. 

Table 5-3. Terminals Supported by MPE 



TERMINAL DESCRIPTION 

TYPE 



HP 2749B (ASR-33 El A compatible) Terminal { 1 characters per second (cps) ). 

1 ASR-37 Teleprinter Terminal with Paper Tape Reader/Punch (10 cps). 

2 ASR-35 ElA-compatible Terminal (10 cps). 

3 Execuport 300 Data Communications Transceiver Terminal (10/15/30 cps). 

4 HP 2600A or Datapoint 3300 Keyboard Display Terminal (10/15/30/60/120/240 cps). 

5 Memorex 1240 Communications Terminal (10/15/30/60 cps). 

6 HP 2762A/B (General Electric Terminet 300 or 1200), or Data Communications Terminal, 
Model B (10/15/30/120 cps) with Paper Tape Reader/Punch, Option 2. 

9 HP 261 5A Terminal (Beehive MiniBee) (10/15/30/60/120/240 cps). 

10 HP 2640A/B, HP 2641 A, HP 2644A, or HP 2645A Character Mode or full program control of 
block mode transmission (10-240 cps). 

11 HP 2640A/B, HP 2641 A, HP 2644A, or HP 2645A. Allows user to use block mode without 
program control of block mode transmission. Requires user to position cursor before pressing 

. r • i; on ...U An .. nll oun(w»t fn c\A/itrh hptwppn 

ENTER. Kecommenaea Tor speeas exceeumy ju <jv* »»uci. , uu v^- -^ 

character mode and block/line mode. May not be used in block/page mode. (10-240 cps.) 

1 2 HP 2645K Katakana/Roman Data Terminal. 

1 3 Message switching network or other computer. 

14 Multi point Terminal. 

1 5 HP 2635A Printing Terminal. 8-bit protocol (for second character set). 

16 HP 2635A Printing Terminal. 7-bit protocol (standard character set). 
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NOTE 

The line correction mechanism (H c ) works in the following 
ways for all terminals including the system console: 

• CRT Terminals 

All currently supported CRT terminals can physically 
backspace the cursor; therefore, H c causes the cursor to 
be backspaced one position, leaving the cursor posi- 
tioned over the character to be replaced. The physical 
backspacing of the cursor does not erase the character 
from the screen, but the character has been deleted 
from MPE's internal buffer. 

• Hardcopy Terminals 

a. Terminals which have physical backspace 
capability: 

H c causes a physical backspace to occur. In 
addition, a line feed is performed unless the 
previous character also was a H c . The result is 
that you begin typing beneath the first character 
to be replaced. 

b. Terminals with no physical backspace capability: 
No backspacing takes place. Each H c echoes a 
backslash (\) unless in tape mode. 

CHANGING TERMINAL CHARACTERISTICS. Certain aspects of terminal operation can be 
changed with the FSETMODE, FCONTROL, and PTAPE intrinsics. Before these intrinsics can be 
used in a program to change terminal characteristics, however, the terminal/file must be opened 
with the FOPEN intrinsic. 

Changing Terminal Speed. MPE supports terminals that run at speeds ranging from 10 to 240 
characters per second (cps). You can programmatically change these speeds with the FCONTROL 
intrinsic. This capability allows a user running a mark sense card reader coupled to a terminal to 
operate the two devices at different speeds (for example, the card reader at 240 cps for input and 
the terminal at 10 cps for output). The FCONTROL intrinsic is not valid for terminals that operate 
at only one speed. 

The format for this application of the FCONTROL intrinsic is 



IV IV L 

FCONTROL(filenum,controicode,speed); 

The parameters are 

filenum integer by value (required) 

A word identifier supplying the file number of the terminal for which 
the speed is to be changed. 
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controlcode integer by value (required) 

The decimal integer 10 to change the input speed or 11 to change the 
output speed. 

speed logical (required) 

A word identifier that specifies the new speed desired: 10, 14, 15, 30, 
60, 120, 240, 480, or 960, cps. When the FCONTROL intrinsic is exe- 
cuted, the previous input or output speed is returned to the calling 
process through the speed parameter. 

The condition codes are 

CCE Request granted. 

CCG Not returned by this application of FCONTROL. 

CCL Request denied. The process does not owr> the logical device, or this 

device is not a terminal, or the speed entered is not acceptable. 

As an example, to change the current input speed of the terminal identified by the file number 
stored in the word TERMFN from 60 to 120 cps, the following call could be used. The word 

FCONTROL(TERMFN,10,SPEED); 

After the intrinsic is executed, the word SPEED contains the integer 60 (the previous speed). 

Changing Input Echo Facility. You can programmatically determine whether MPE transmits 
(echoes) input from the terminal keyboard back to the terminal printer by calling the FCONTROL 
intrinsic to turn the echo facility on or off. 

When the echo facility is on, input read from the terminal is echoed to the terminal's printer by 
MPE. If the terminal is operating in full-duplex mode, the echoed information appears as normal 
printed lines. If the terminal is in half-duplex mode, however, the echoed printing is illegible — as 
you enter input on such terminals, it is simultaneously printed by the terminal itself and 
subsequently overwritten by the echoed information. Where a terminal can operate in either full- or 
i \c j i j» 4-u„ ™„^,~ Jo c^r^inA Kit a cjTiri+/-.V> <-.« tho terminal WVipn vnn lncf nn_ all terminals 

are assumed to have the echo facility on. 

When the echo facility is off, input read from the terminal is not echoed to the terminal's printer by 
MPE. If the terminal is operating in fuii-dupiex mode, no printing appears. If the terminal is in 
half-duplex mode, the input is copied by the terminal itself, and appears as normal, printed lines. 
Bear in mind that the only way printing can be suppressed is with the echo facility off and the 
terminal in full-duplex mode, as illustrated in figure 5-1. 

In addition to the FCONTROL intrinsic, the echo facility also can be switched on and off by 
entering the characters: 

ESC: to turn the echo facility on. 
ESC; to turn the echo facility off. 
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Figure 5-1. Echo Facility vs Duplex Mode 



The format for this application of the FCONTROL intrinsic is 

IV IV L 

FCONTROL(filenum,controlcode,last); 




H 



HALF-DUPLEX 



<h 



PRINTLINE 



PRINTING 



F 



The parameters are 
filenum 



integer by value (required) 

A word identifier supplying the file number of the terminal. 
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controlcode integer by value (required) 

lilt: lUbCgCX 1^ IAJ IU111 OXX*3 CV/llU XCU,XiXuy UU, vx J-x^ wtr wi**.** *v xJ~-^. 

to? logical (required) 

A word identifier to which the previous echo facility is returned, where 

= echo on 

1 = echo off. 

The condition codes are 

CCE Request granted. 

CCG Not returned by this application of FCONTROL. 

CCL Request denied because the file number specified did not belong to this 

process or this device is not a terminal. 

As an example, to turn the echo facility off, the following intrinsic call could be used: 

FCONTROL(TERMFN,13,LAST); 

.Ml LCI UJ.1C lill/llllOlC 13 CACL>UUCVl) W1C WviU j_j^"it^ J. vwiinftuiu vxa^ t Cmuu w w^ -*. «w *.^j._ vv .; ^ >. a- 

facility status. 

Enabling and Disabling System Break Function. You can programmatically suspend or enable a 
terminal's ability to react to a system break request with the FCONTROL intrinsic. System break 
requests are initialized by pressing the BREAK key or by calling the CAUSEBREAK intrinsic. 

The format for this application of the FCONTROL intrinsic is 

IV IV L 

FCONTROL(filenum,controlcode,anyinfo); 



The parameters are 
filenum 



controlcode 



anyinfo 



integer by value (required) 

A _J I ^~~.4-l£l~~ n .i««l.nv.H 4-lxn -Pil« niimknt* ^"f +V» rt f^^rMlTlol 

£\. WUIU lLlCIltlXXCX OlXppxyxlXg bUC xxxc xxixxxxura. \yx uxx^ uuuuuui. 

integer by value (required) 

The integer 15 to enable the break function, or 14 to disable the break 

function. 

logical (required) 

Any variable or word identifier. This parameter is needed by 
FCONTROL to satisfy the internal requirements of this intrinsic; 
however, it serves no other purpose and is not modified by the intrinsic. 



The condition codes are 



CCE 



Request granted. 
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CCG Not returned by this application of FCONTROL. 

CCL Request denied because the file number specified did not belong to this 

process or the device is not a terminal. 

As an example, to enable the break function, the following intrinsic call could be used: 

FCONTROL(TERMFN,15,DUMMY); 

Enabling and Disabling Subsystem Break Function. All terminals are initially set to disable (not 
accept) subsystem break requests, generated by entering CONTROL-Y during a session. You can, 
however, programmatically enable and again disable a terminal's ability to react to subsystem break 
requests with the FCONTROL intrinsic. 

The format for this application of the FCONTROL intrinsic is 

IV IV L 

FCONTROL(filenum,controlcode,anyinfo); 

The parameters are 

fllenum integer by value (required) 

A word identifier supplying the file number of the terminal. 

controlcode integer by value (required) 

The integer 17 to enable the subsystem break function, or 16 to disable 
the subsystem break function. 

anyinfo logical (required) 

Any variable or word identifier. This parameter is needed by 
FCONTROL to satisfy the internal requirements of this intrinsic; 
however, it serves no other purpose and is not modified by the intrinsic. 

The condition codes are 

CCE Request granted. 

CCG Not returned by this application of FCONTROL. 

CCL Request denied because the file number specified did not belong to this 

process or the device is not a terminal. 

As an example, to enable the subsystem break function, the following intrinsic call could be used: 

FCONTROL(TERMFN,17 .DUMMY) ; 

Enabling and Disabling Parity Checking. All terminals and mark-sense card readers are initially set 
to disable parity checking during read operation. They may, however, be programmatically enabled 
for parity checking with the FCONTROL intrinsic. Then, the parity of the data received is checked 
against the parity computed by the asynchronous channel multiplexer. If a parity error is detected, 
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an error code is made available through the FCHECK intrinsic. When you are running a card reader 
coupled to a terminal, the ability to enable/disable parity checking allows you to obtain optimum 
utilization of the card reader by running it at 240 characters per second. These control code options 
are not valid for terminals configured as termtype 12 (HP 2645K). 

The format for this application of the FCONTROL intrinsic is 

IV IV L 

FCONTROL(filenum,controlcode, any info ) ; 



The parameters are 
filenum 

controlcode 
anyinfo 



integer by value (required) 

A word identifier supplying the file number of the terminal. 

integer by value (required) 

The integer 24 to enable parity checking, or 23 to disable parity 

checking. (Not valid for termtype 12 (HP 2645K).) 

Any variable or word identifier. This parameter is needed by 
FCONTROL to satisfy the internal requirement of this intrinsic; 

Vi j-tTxKwrja*. 1+ cgmrac r>r\ /-vH-»al» nnrnnco anrl ic nnf mo^lfl^H h\7 "Hip in tnnSlf 1 



The condition codes are 



CCE 



Request granted. 



CCG 

CCL 



Not returned by this application of FCONTROL. 

Request denied because the file number specified did not belong to this 
process or the device is not a terminal. 



As an example, to enable parity checking, the following intrinsic call could be used: 
FCONTROL(TERMFN,24,DUMM Y) ; 



tape-mode option for a terminal with the FCONTROL intrinsic. When enabled, the tape-mode 
option inhibits the implicit line feed normally issued by MPE each time a carriage return is entered. 
The tape mode option also inhibits responses to H c and X c entries. Thus, when H c is received and 
tape mode is in effect, no exclamation points (!!!) are sent to the terminal. To inhibit carriage 
return, linefeed after READ or FREAD, use FSETMODE (see page 2-84). 

The format for this application of the FCONTROL intrinsic is 



IV IV L 

FCONTROL(filenum,controlcode,anyinfo); 
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The parameters are 
filenum 

controlcode 

anyinfo 



The condition codes are 

CCE 

CCG 

CCL 



integer by value (required) 

A word identifier supplying the file number of the terminal. 

integer by value (required) 

The integer 19 to enable tape mode, or 18 to disable tape mode. 

logical (required) 

Any variable or word identifier. This parameter is needed by 

FCONTROL to satisfy the internal requirements of this intrinsic; 

however, it serves to other purpose and is not modified by the 

intrinsic. 



Request granted. 

Not returned by this application ofFCONTROL. 

Request denied because the file number specified did not belong to this 
process or the device is not a terminal. 



As an example, to enable tape mode, the following intrinsic call could be used: 

FCONTROL(TERMFN,19,DUMMY); 

Enabling and Disabling The Terminal Input Timer. The terminal input timer records the time 
required to satisfy an input request on the terminal, from the time the input is requested until it is 
completed. This applies only to unbuffered, serial terminal input requests. You can program- 
matically enable or disable the terminal input timer with the FCONTROL intrinsic. 

The format for this application of the FCONTROL intrinsic is 

IV IV L 

FCONTROL(filenum,controlcode,anyinfo); 



The parameters are 
filenum 

controlcode 

anyinfo 
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integer by value (required) 

A word identifier supplying the file number of the terminal. 

integer by value (required) 

The integer 21 to enable the time, or 20 to disable the timer. 

logical (required) 

Any variable or word identifier. This parameter is needed by 
FCONTROL to satisfy the internal requirements of this intrinsic; 
however, it serves no other purpose and is not modified by the intrinsic. 



The condition codes are 

CCE Request granted. 

CCG Not returned by this application of FCONTROL. 

CCL Request denied because the file number specified did not belong to this 

process or the device is not a terminal. 

Figure 5-2 contains a program that generates an ASCII character, instructs the user to enter this 
character on the terminal, then measures and displays the reaction time of the user. 

The statement 

FCONTROL(IN,21,DUMMY); 

enables the terminal input timer so that the reaction time of the user can be measured. The 
parameter IN supplies the file number of the terminal and was obtained through the FOPEN 
intrinsic call (see statement 19 in the program). 

NOTE 

The statement 

FCONTROL(IN,4,TIMEOUT) ; 

is used to set a time out on FREAD. This application of 
FCONTROL is used in conjunction with FREAD intrinsic 
calls issued against the terminal. The time-out interval speci- 
fied in this case is 10 seconds (see statement number 5 in the 
program). If there is no response to the FREAD intrinsic 
call (see statement number 33) within 10 seconds, a CCL 
condition code is returned and the program displays the 
message 

YOU'RE TOO SLOW 
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00020 1 
000 31 1 

00021 1 
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00041 1 
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00 120 1 
00126 1 
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00134 2 
00141 2 
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00 153 1 
00157 1 
00162 1 
0O171 1 
0017 7 1 
00202 1 
00202 1 
00207 1 
00212 1 
00220 1 
00??4 1 
00232 1 

H STORAGE 
S = 0()0! 

riMF=o:o 



SCONTKOL USLlNlT 
BFGIN 

BYTE ARRAY INNAME ( : 5 ) : =" I NPUT "? 

BYTE ARRAY OUTNAMF ( : 6 ) i ="OUTP JT "I 

INTEGER I N, OUT, LGTH.DUMMY, TIME, TIMEOUT: = 10; 

ARRAY BUFR(o:3> :="TYPE X»,05 

BYTF ARRAY CBUF <*) =BUFR| 

ARRAY INSTRIICTIONS(0:34) :="REACTION TIMER: ",*6412, 

"TYPE THE REQUESTED CHARACTER AS QUICKLY AS YOU CAN. »» 

ARRAY MSG(0:24) :=»TRY AGAIN? ( Y/N) ■<, "WRONG CHARACTER.", 
*6412. "YOU'RE TOO SLOW!"; 

ARRAY RESP0NSE(0:i6) !=»R£ACT10M TIME: MILLISECONDS'.; 

BYTE ARRAY CKFSP ( * ) =RESPONSE S 

INTRINSIC FOPEN.FRt AD, FWRITE.FCONTROL, ASCI I, TIMER, QUIT; 
<<fc'NI) OF L>ECLARAIIOMS>> 



LOOP] 



NEXT! 



ENO. 
=*016; 

0:03; 



lNi:=F0PFH(INNAME.*,4b) 5 

IF < THEN QUITO) ! 

0UT:=F0PEN(0UTNAMF_,%414,*1 ) ; 

IF < THFN ,JUI7 (?) ; 

F WRITE (OUT, INSTRUCT IONS. 35,0) ; 

IF < THEN UUIT13! ; 

F.C0«TR0L(IN.21»DLH*>»Y) t 

if < THgN WIT (4}$ 

FCONTROL ( IN, 4. TIMEOUT) ; 

IF < THEN QUIT(b) ; 

C«UF<5) :=INTEGER(TIMER).(li:5)t»73; 

FWRITF(OUT,BUFR,3,*320) « 

IF < THEN 0UIT(6) ! 

LGTH:=FREAD(IN,BUFR(3) ,-n ; 

IF < THt-N 

BEGIN 

FWRITE(0UT,MSG(16) ,9,0) ; 

IF < THEN UIIIT(7) ELSF GO next; 

end; 

IF CHl.iF (b) OCBHF (6) THEN 
BEGIN 

FWRITE(0UT,MSG(8) ,8,0) ; 
IF < THFN OUTT(B) LLSE GO NFXT5 
ENDS 
rtOVr. RESPONSE (7) :=" >■: 

FCCWTHOt 1IN»2?»TIM£> l 
IF Tn£N QUIT (9) 5 

Ascn ( riM t «io,io.cwESP(i5) ) ; 

F WR I TF( OUT, RESPONSE, 17,0) ; 
IF < THFN OUIT (10) ! 

F WRITE (OUT,MSG,8,%320) ; 

IF < THFN OUIT( 11) » 

FREA[)(IN,HUFR(3) ,-1) ; 

IF < THEN 0UITU2) » 

IF CflUF(6)="r'" THEN GO LOOP; 

SECONDARY OB STORAGE=*0Oi 30 
NO. WARNINGS=00n 
ELAPSED riME=0:00:10 



<<SSTDIN>> 
<<CHECK FOR ERROR>> 
<<SSTDLIST>> 
<<CHECK FOR ERROR>> 
<<USER DIRECTIONS>> 
<<CHECK FOR ERR0P>> 

«EHABU TIM£R «FJf»> 

«CH€etc run tfeftOff*> 

<<ENABLE TIMEOUT>> 
<<CHECK FOR ERROR>> 
<<GENERATE A CHARACTERS 
<<REQUEST USER INPUT>> 
<<CHECK FOR ERROR>> 
<<READ CHARACTER>> 
<<TIMEOUT OCCURRED>> 

<<TOO SLOW MESSAGE>> 
<<CHECK FOR ERROR>> 

<<INCORRECT CHARACTER>> 

<<WRONG CHARACTER MESSAGE>> 
<<CHECK FOR ERROR>> 

<<RESET RESPONSE TIME>> 
«REA0 INPUT TIME» 
«CHECK FOH €RRFO»» 
<<CONVERT TIME>> 
<<REACTION TIME>> 
<<CHECK FOR ERROR>> 

<<C0NTINUE TEST?>> 
<<CHECK FOR £RR0R>> 
<<GET Y/N ANSWER>> 
<<CHECK FOR ERROR>> 
<<Y-CONTINUE TEST>> 



Figure 5-2. Using the FCONTROL Intrinsic to Enable and Read the Terminal Input Timer 
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The results of running the program of figure 5-2 are shown below: 



: RUN TIME 

REACTION TIMER: 

TYPE THE REQUESTED CHARACTER AS QUICKLY AS 

TY^E M 

YOU'RE TOO SLOW! 

TRY AGAIN? (Y/N)Y 

TYPE >>. 

REACTION TIME: 9670 MILLISECONDS 

TRY AGAIN? CY/N>Y 

TYPE B3 

REACTION TIME: 4090 MILLISECONDS 

TRY AGAIN? CY/N)Y 

TYPE UU 

REACTION TIME: 1790 MILLISECONDS 

TRY AGAIN? <Y/N)Y 

TYPE 10 

WRONG CHARACTER. 

TRY AGAIN? (Y/N)N 

END OF PROGRAM 



Reading The Terminal Input Timer. You can read the result from the terminal input timer with 
the FCONTROL intrinsic. The result will be valid only if the terminal input was preceded by a call 
to enable the terminal input timer. If valid, the result is the time, in hundredths of seconds, required 
for the last direct, unbuffered serial input on the terminal. 

The format for this application of the FCONTROL intrinsic is 

IV IV L 

FCONTROL(filenum,controlcode,inputtime); 



The parameters are 
filenum 



integer by value (required) 

A word identifier supplying the file number of the terminal. 



controlcode 



integer by value (required) 
The integer 22. 
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inputtime logical (required) 

A word to which is returned the input time (in seconds/100). 

The condition codes are 

CCE Request granted. 

CCG Request granted, but the result overflowed 16 bits {inputtime was 

greater than 655.35 seconds). 

CCL Request denied because the file number specified did not belong to this 

process or the device is not a terminal. 

Refer to figure 5-2. The statement 

FCONTROL(IN,22,TIME); 
reads the result from the terminal input timer. This result is returned to the word TIME. 
The statement 

ASCII(TIME*10,10,CRESP(15)); 

multiplies the value of TIME by 10 and converts this result to an ASCII string so that the user's 
reaction time, in milliseconds, can be displayed. The resulting ASCII string is stored in the byte 
array CRESP, starting at the 16th position (CRESP(15)). The statement 

FWRITE(OUT,RESPONSE,17,0); 

displays the reaction time. (Arrays CRESP and RESPONSE have been equivalenced, see statements 
12 and 13.) 

Defining Line-Termination Characters for Terminal Input Normally, when using a terminal, you 
indicate the end of a line by entering a carriage return (with the RETURN key on most terminals). 
With the FCONTROL intrinsic, however, you can specify that an additional character, such as an 
equal sign, a period, or an exclamation point, be recognized as the standard line terminator. On 
subsequent read operations during your process, the input line is terminated by the specified 
character. That character is returned to your buffer. No carriage return or line feed is generated. 

The format for this application of the FCONTROL intrinsic is 

IV IV L 

FCONTROL(filenum,controlcode,character); 

The parameters are 

fUenum integer by value (required) 

A word identifier supplying the file number of the terminal. 
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controlcode 



character 



integer by value (required) 
The integer 25. 

logical (required) 

A word identifier supplying (in the right byte) the character to be used 

as a line terminator. The left byte of this word can contain any 

information — it is ignored by the intrinsic. If zero is specified in the 

character parameter, the terminal reverts to its normal line-control 

operation. 



The condition codes are 

CCE 

CCG 

CCL 



Request granted. 

Not returned by this application of FCONTROL. 

Request denied because the file number specified did not belong to this 
process or the device is not a terminal. 

The following characters are not recognized as line-terminating charac- 



i>fcU.G u.u.img iiu.lj.iicu icauo. 



ASCII Character 

Backspace (H c ) 

Line Feed (J c ) 

Carriage Return (M c ) 



X-ON 

DC2 

X-OFF 

Line Delete 

Control-Y 

Escape 

Del 



(Q C ) 
(R c ) 

(S c ) 
(X c ) 
(Y c ) 

« C ) 



Octal Code 

10 
12 
15 
21 
22 
23 
30 
31 
33 
177 



As an example, to specify a period as the standard line terminator for a terminal, the following 
intrinsic call could be used: 

FCONTROL(TERMFN,25,CHAR); 

The word CHAR contains the octal value %56 (indicating a period) in the right byte. (The left byte 
can be specified as any value.) 

Enabling and Disabling Binary Transfers. Binary transfers can be enabled or disabled with the 
FCONTROL intrinsic. (Binary transfers are disabled in normal MPE operation.) 

The format for this application of the FCONTROL intrinsic is 

IV IV L 

FCONTROIj(filenum,controlcode,anyinfoy, 
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The parameters are 
fllenum 

controlcode 
anyinfo 



The condition codes are 

CCE 

CCG 

CCL 



integer by value (required) 

A word identifier supplying the file number of the terminal. 

integer by value (required) 

The integer 26 to disable binary transfers, or 27 to enable binary 

transfers. 

logical (required) 

Any variable or word identifier. This parameter is needed by 
FCONTROL to satisfy the internal requirements of this intrinsic; how- 
ever, it serves no other purpose and is not modified by the intrinsic. 



Request granted. 

Not returned by this application of FCONTROL. 

Request denied because an error occurred. 



Enabling and Disabling User Block Transfers. User mode block transfers (to or from block mode 
terminals such as the HP 2644/2645) can be enabled or disabled with the FCONTROL intrinsic. 
(User mode block transfers are disabled in normal MPE operation.) 

The format for this application of the FCONTROL intrinsic is 

IV IV L 

FCONTEOL(menum,controlcode,anyinfo); 



The parameters are 
filenum 

controlcode 
anyinfo 



The condition codes are 

CCE 

CCG 

CCL 



integer by value (required) 

A word identifier supplying the file number of the terminal. 

integer by value (required) 

The integer 28 to disable user mode block transfers, or 29 to enable 

user mode block transfers. 

logical (required) 

Any variable or word identifier. This parameter is needed by 
FCONTROL to satisfy the internal requirements of this intrinsic; how- 
ever, it serves no other purpose and is not modified by the intrinsic. 



Request granted. 

Not returned by this application of FCONTROL. 

Request denied because an error occurred. 
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Enabling and Disabling Line Deletion Echo Suppression. In normal MPE operation, Control-X is 
interpreted as a line deletion operation and the character string "!!!" is echoed on the terminal. 
You can suppress the line deletion echo, so that the character string is not displayed on the terminal, 
with the FCONTE.OL intrinsic. 

The format for this application of the FCONTROL intrinsic is 

IV IV L 

FCONTROL(filenum,controlcode, any info); 



The parameters are 
filenum 

controlcode 
anyinfo 



The condition codes are 

CCE 

CCG 

CCL 



integer by value (required) 

A word identifier supplying the file number of the terminal. 

integer by value (required) 

The integer 34 to disable the line deletion echo, or 35 to enable the line 

deletion echo. 

logical (required) 

Any variable or word identifier. This parameter is needed by 
FCONTROL to satisfy the internal requirements of this intrinsic; how- 
ever, it serves no other purpose and is not modified by the intrinsic. 



Request granted. 

Not returned by this application of FCONTROL. 

Request denied because an error occurred. 



Setting Parity. The FCONTROL intrinsic can be used to specify the parity, if any, to be used in 
transmitting data to a terminal. Parity is generated on the right seven bits or the full eight bits of a 
character. This controlcode option is not valid for terminals configured as termtype 12 (HP 2645K). 

The format for this application of the FCONTROL intrinsic is 

IV IV L 

FCONTROL(filenum,controlcode,param); 



The parameters are 
filenum 

controlcode 



integer by value (required) 

A word identifier supplying the file number of the terminal. 

integer by value (required) 

The integer 36. (Not valid for termtype 12 (HP 2645K).) 



5-25 



param logical (required) 

A logical word, as follows: 



The condition codes are 



- No parity generated. All eight bits are transmitted. 

1 - No parity generated. Bit 8 is always set to 1. 

2 - Even parity generated if bit 8 is 0; odd parity generated if bit 8 is 1. 

3 - Odd parity generated on seven bits. (This is the normal mode of 

operation.) 



CCE Request granted. 

CCG Not returned by this application of FCONTROL 

CCL Request denied because an error occurred. 

Allocating a Terminal. A terminal can be removed from speed-sensing mode, initialized according to 
the type and speed specified by the FCONTROL intrinsic, and set on line. (The terminal cannot be 
configured as :JOB or :DATA accepting.) 

The format for this application of the FCONTROL intrinsic is 

IV IV L 

FCONTROL(filenum,controlcode,param); 

The parameters are 

filenum integer by value (required) 

A word identifier supplying the file number of the terminal. 

controlcode integer by value (required) 

The integer 37. 

P aram logical (required) 

A logical word, as follows: 

Bits (11:5) - Terminal type (see page 5-8). 

Bits (0:11) - Speed in characters per second. 



The condition codes are 



If param is set to zero, the speed and terminal type specified when the 
system was configured will be used to initialize the device. 



CCE Request granted. 

CCG Not returned by this application of FCONTROL. 

CCL Request denied because an error occurred. 
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Setting Terminal Type. The terminal type can be set with the FCONTROL intrinsic. 
The format for this application of the FCONTROL intrinsic is 

IV IV L 

FCQNTROUfflenum,controlcode,param); 

The parameters are 



filenum 
controlcode 

param 

The condition codes are 

CCE 

CCG 

CCL 



integer by value (required) 

A word identifier supplying the file number of the terminal. 

integer by value (required) 
The integer 38. 

logical (required) 

A logical word specifying the terminal type (see page 5-8). 

Request granted. 

Not returned by this application of FCONTROL. 

Request denied because an error occurred. 



Obtaining Terminal Type Information. The terminal type can be determined with the FCONTROL 

intrinsic. 

This application of FCONTROL may be used before a terminal is allocated (with FCONTROL 
controlcode parameter 37, see page 5-24) to return the terminal type specified when the system was 
configured. A value of 31 is returned in param if no terminal type was specified at configuration time. 

The format for this application of the FCONTROL intrinsic is 

IV IV L 

FCONTROL(filenum,controlcode,paramy, 



The parameters are 



controlcode 
param 

The condition codes are 

CCE 

CCG 

CCL 






A word identifier supplying the file number of the terminal. 

integer by value (required) 
The integer 39. 

logical (required) 

A logical identifier to which is returned the terminal type (see Table 

5-3) as specified at log-on time or when the terminal was allocated. 



Request granted. 

Not returned by this application of FCONTROL. 

Request denied because an error occurred. 



5-27 



^ST?J em ; inal ° UtPUt Speed - The terminal ° utput S P eed can be determined with the 
r CONTROL intrinsic. 

This application of FCONTROL may be used before a terminal is allocated (with FCONTROL 
controlcode parameter 37, see page 5-24) to return the speed specified when the system was configured 
A value of zero is returned in param if no speed was specified at configuration time. 

The format for this application of the FCONTROL intrinsic is 

IV IV L 

FCOKTROL(filenum,controlcode,param); 

The parameters are 

filenum integer by value (required) 

A word identifier supplying the file number of the terminal. 

controlcode integer by value (required) 

The integer 40, 

param logical (required) 

A logical identifier to which the terminal output speed in characters per 



second is returned. 



The condition codes are 



CCE Request granted. 

CCG Not returned by this application of FCONTROL. 

CCL Request denied because an error occurred. 

Setting Unedited Terminal Mode. The terminal can be set in unedited mode with the FCONTROL 

intrinsic. In unedited mode, all characters, except those that you can specify for Attention and 

end-of-record, are passed to the terminal. Note that only seven bits of the characters are passed- the 

parity bit is stripped. 

The end-of-record character terminates input from the terminal in unedited mode (as a carriage 
return does in normal mode). 

The Attention character terminates input and causes a Subsystem Break in unedited mode (as a 
Control-Y does in normal mode). 

No automatic line feed is output to the terminal when input terminates in unedited mode. 

The unedited mode is reset to normal when an FCLOSE intrinsic call is issued against the terminal 
or when the chars parameter of FCONTROL equals zero. (See below.) 

The unedited mode is disabled while the terminal is in Break or Console mode. 

The format for this application of the FCONTROL intrinsic is 

IV IV L 

FCONTEOU filenum.controlcode, chars); 
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The parameters are 
filenum 

controlcode 
chars 



The condition codes are 

CCE 
CCG 
CCL 



integer by value (required) 

A word identifier supplying the file number of the terminal. 

integer by value (required) 
The integer 41. 

logical (required) 

A logical word, as follows: 

Bits (0:8) - Attention character. 

Bits (8:8) - End-of -record character. 

If chars = 0, the unedited mode is reset to normal. 



Request granted. 

Not returned by this application of FCONTROL. 

Request denied because an error occurred. 



Reading Paper Tapes Without X-OFF Control. The X-OFF control character, written by pressing 
the X-OFF key on a teletype terminal, is used to delimit data input on paper tape. When a teletype 
tape' reader encounters this character while reading a tape, reading halts until the program requests 
more input data. 

You can programmatically read data from paper tapes not containing the X-OFF control character, 
or from tapes input through terminals not recognizing this character with the PTAPE intrinsic.^ 
the latter case the X-OFF characters are stripped from the tape. Tape input terminates when Y is 
encountered, returning control to the terminal. Prior to calling the PTAPE intrinsic, you must be 
sure to position the end-of-file pointer to the proper position in the file. If you are reading more 
than one tane. vou should specify, in the FOPEN intrinsic call that opens the file, the append-only 
access type 'and a variable-length record format before the first PTAPE intrinsic call. Additionally, 
you should' set the end-of-file pointer to zero, if necessary, before issuing the first PTAPE intrinsic 
call. 

A PTAPE intrinsic call such as 

PT APE(TERMFN,DISCFL) ; 

could be used to read a paper tape not containing the X-OFF control character, or to read a paper 
tape input through a terminal that does not recognize this character. The data would be stored in 
the disc file whose file number is specified by DISCFL. 

To inhibit carriage return, linefeed after READ or FREAD, use the FSETMODE intrinsic (see 
page 2-84). 
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USING THE FCARD INTRINSIC TO OPERATE THE HP 7260A OPTICAL MARK READER 

The FCARD intrinsic allows you to control the operation of the HP 7260A Optical Mark Reader 
(OMR) programmatically. This is achieved through passing a parameter value (recode), correspond- 
ing to the function of FCARD desired, from a program to FCARD. FCARD returns to the calling 
program parameter values which indicate the success or the cause of failure of execution the status 
of the 7260 A, the file number of the 7260A/terminal file for which the function has been per- 
formed and the number of columns read at the completion of a read request. 

The program shown in figure 5-3 performs the following: 

1. Opens the 7260A/terminal file. 

2. Displays operator instructions. 

3. Temporarily suspends program operation awaiting the depression of the 7260A READY switch 

4. Reads ten cards in the ASCII reading format. 

5. Displays the number of columns read from each card. 

6. Examines status for empty input hopper status. 

7. Examines output recode values of each request. 

8. Closes the 7260A/terminal file. 

Under the label OPENFILE, the program requests that a 7260A/terminal file be opened for access 
and that the file number of this file be returned to the program in the parameter filenum by assign- 

^a ™ C + °u a ^^ ° f ° and CalUng FCARD M illustrate d- When process control is returned from 
nSt^ ^ Program verifies that the call was successful (recode=0) and continues at the label 
DibFlNbT. Under this label, operator instructions are displayed on the $STDLIST device If the 
call to FCARD was unsuccessful (recode¥=0), then the error message "CAN NOT OPEN FILE - 
PROGRAM WILL TERMINATE" is displayed and the program goes to the label FINIS and 
terminates. 

Under the label RDYWAIT, a display instructing the operator to press the READY switch is given 
and the request for a temporary suspension of the program awaiting the depression of the READY 
switch is made by setting recode equal to 4 and calling FCARD as illustrated. The program unon 
regaining process control, checks for unsuccessful execution of the request (checks for recodeio) 
If the execution was unsuccessful, the program goes to the label FINIS and terminates (NOTE- The 
program could have branched to an error correcting or displaying instruction set if desired by the 
programmer). If the execution was successful, the program continues with the next statement 
which is under the label READ'. 

Under the label READ', the program requests the reading of ten cards by setting recode equal to 1 
and calling FCARD as illustrated. Upon return of the process control from FCARD the prol m 

Z2t;L7^^r ti0n {reC ° M) - " ^ e " ^ ~ <* *. p P roSm 

Under the label READ'ERR, the program determines the value of recode returned after the read 
request and initiates corrective action and/or displays an appropriate error message o ^term nates 
itself, depending on the value of recode detected . terminates 
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If the execution was successful, the program checks status for an empty input or full output hopper 
condition and if this status condition is detected, the program goes to the label HOPPERS under 
which corrective steps are initiated. If this status condition is not detected, the program calls a 
procedure (DISP'COUNT) which displays the number of columns read from the previous card. 
After the DISP'COUNT procedure is completed, the program goes to the label CLOSET. 

Under the label CLOSE'F, the program requests that the 7260A be put in the not READY state 
and that the 7260A/terminal file be closed by setting recode equal to 10 and calling FCARD and 
by setting recode equal to 20 and calling FCARD, respectively. In both cases, the value of recode 
returned from FCARD is examined for an indication of successful execution as illustrated. 



ASCII AND COLUMN IMAGE READING FORMATS 

In the ASCII mode (also called the Hollerith mode) the OMR recognizes 128 character Hollerith 
codes and transmits one 7 bit serial ASCII character plus an even parity bit per card column. 
FCARD packs two ASCII characters (two columns of data) into each buffer word in bufadr. The 
data from the first column of the card is stored in the upper byte of the first word of the buffer, 
as illustrated below. 



1st word 



2nd word 



1st column data 


2nd column data 


3rd column data 


4th column data 



In the column image mode, the OMR transmits a 12-bit data string, representing the twelve rows of 
one card column. FCARD packs the first 12-bit data string (the first column of data) into the first 
buffer word in bufadr, as illustrated below. 



Buffer Word 



— 


— 


— 


— 


12 


11 





1 


2 


3 


4 


5 


6 


7 


8 


9 














X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 

— — 



1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 
X — indicates that bit may be either logical 1 or 0. 



column row no. 

data 

bit no. 
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ICONTPOL USLIMII 

tf£GIN 

INTEGER ARRAY RUFADR{0:99) J 

BYTE ARRAY TOO(0:7?); 

POINIEB HERE! 

INTetEP BECOr>E,A,I; 

INTRINSIC QUIT, PRINT; 

INTEfi£fi COUNI/FlLENUM, STATUS; 

INTRINSIC PRINT'FlLE'lNFf); 



PROCFOURE DlSP-COUNT(COUNT) ; 
IH.IS.GEH COUNT; 

BEGIN 

ARfiJy UUT(0:11 ); 
BYTF ARRAY "OUT f * )=OUT ; 
INTRINSIC PRINT, ASCII: 
INTEGER A1,A<!: 



MDVE BOUT:="NO. OF COLUMNS READ= "; 
A) : = ASCTKcnuNT, 10, bout (21 ) ) ; 
A?:i -£1-M ; 
PPINI(OUT,Aa,)!it011; 

END) 

PROCEOllpF FCApri(RFCODE,FlLFNUM,«llFADR f COUNT , STA TIIS) : 

INTECFR ARPA' BUFAORj 

INTEGER PECOOfc.FILEMIM, COUNT, STATUS; 

OPTION EXTERNAL; 



„lHERF:Xi>Ton 8 I SR(1 )• 
OPENFILE: 

<<GFT FTLF NUMBER FOR LOGICAL OEV EQUAL TO THE TERMINAL>> 

RFCODESSOT 

FCARn r RECODF.FI LENUM,BUF ADR, CUUNT, STATUS); 

IF Rf-COOE 10 THEN SO 0TSPIN8T; 

MOVf TOO:s"CAN NOT OPFN FILE-PPOGRAM WILL TERMINATE"; 

PRINrfHFPE,-<JO,0) ; 

GO FfNIS; 

DISPINST; 

wove Tnn : =rxis,»i?): 

PRINT(HFRF,_2,oi ; 

MOVE TOOIS'SET THE 7260A FOR CLOCK ON 0A1A."; 

PRINT(HFpE,-i?,0)? 

MOVE TUO : ="PUSH IN THF FULL/HALF SWITCH TO ITS FULL PUSTION 

PRINT(HFRE,.a9,0); 

MOVF TOn::="UN«|lTC THE TFRWINAI.."; 

PRINT(HF?F ,-£">, nj ; 

"OVE TOO:s-LOAD JO CLOr.rf ON OATA CARDS IN THE INPUT HOPPER." 

PRINTfHFRE,-H«,0) : 



Figure 5-3. FCARD Intrinsic Example (1 of 3) 
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roywaiT: 

move TUO: = "NQJi, PRESS 1HE R.EADY SWITCH."! 

PRINT<HERE,-28,0): 

REC0nE:=»! 

FCARD f RECEDE ^FILENUl'UBUFABR.eOUNt, STATUS)! 

a:=oj I :=o: 

IP RFCODfc <>0 THFN GO FINIS; 

READ': 

DO BEGIN 

RECQDE:=l; 

FCARri(RECOOE,FILENUM,BUF ADR, COUNT, STATUS); 

IF fcFCODF <> THEN GO READ'ERR! 
IF STATUS - X67 THEM CO HOPPERS* 
niSP*COUNT(COUNT>S 

T :=I+1 : 

Ei'D 
UNTIL 1=)0; 
GO CLOSE'F; 

HOPPERS! 

RFCODE:=l«; «MAKE 8MR NOT REAQY>> 

FCARDCRECPdE.FILENUM.BUFtDR, COUNT. STATUS) J 
IF RpLont <> THEN 8FGIN 
»:=A+1 : 

IF A<5 THEN GO HOPPERS: 
PRINT'FILF'TNFOIFILENUM)! 

OUlTrRECODE); 

END; 
movf Tnn:="INPUT HOPPFR E H PTY OR OUTPUT HOPPER FULL"; 
PRINT (hFRF,-«0,0) ; 

MOVF Tm; = "COPRECT HOPPER CONDITION AND PRESS READY"; 
PSINTrHERE,-40,0)i 
IF RECOOE <>0 THEN GO FINIS ELSE 

GO KEArt'! 



CLOSE'F: 

REcnnE:=iO: <<wake CR not READy>» 

FC URn rRFCODF,F I LENUM,BUF AD«, COUNT, STATUS)! 

IF RFCODE <> THEN BEGIN 

I : = I + 1 : 

If T < lh THEN GO CLOSF'F: 

PRINT? ILfc ,'ImFOCFILENUM) ; 

END; 
RECODE:=20: 

FC A»n I RF COPF,F I LE W UM,PUF ADR, COUNT, STATUS) ! 
IF RtCODE =n THEN GO FINJS FLSE BEGIN 

"iivt Ti)0: = "liNASLE TO CLOSE THE TERMINAL FILE" 

PplNT(HEPE,-3},0); 

GO FINIS; END: 

RtAD'ERR: 

IF RFCflDF = ft THFN GO RFTRANS; 
IP RECUD6 -'J THEN BEGIN 



Figure 5-3. FCARD Intrinsic Example (2 of 3) 
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"rwE TP0:=»FRF4l> Op FWRlTE ERROR. PROGRAM WILL ABORT"! 

PRINT(HFR£,-UO,0); 

QUITiRtCDDE); END: 



IF RECOOE sfc THEN BEGIN 

MIIVE TnO: = »:EOJ, :FOD, :OATA, OR :JOB FOUND IN INPUT "J 

PRIMTfNeRE,-aa #0 ) ; 

"OVE TOO:="LHEtK CARD VAlioIIY-PRCJGRAM WILL REST»RT"i 

PRIMTC h ERE,-<(0,OI; 

GO DI9PINST; ENDi 
HOVE Ton:="UNl:.TERPREtED ERROR-PROGRAM WILL ABORT"! 
PRINT(HERE,-J7,0): 
QUIT(RECODE); 

RETRANSJ 

REC00E:*3; 

FC&RD»RECODE,FILENUM, B UFADR, COUNT, STATUS) J 

if REcone <> o then begin 

MOVE TPD:="UNSHCCFSSFUL RETRANSMIT-PRUGRAM WILL ABORT") 

PRlNT(HERE,,-<U,a): 

QUIT(RECOOE); END: 

IF STATUS =0 THEN GO READ'; 

«OVE T00::"IINSI1CCESSF1IL RETRANSMIT-PROGRAM WILL ABORT". 

P"IM(rtERt ,-4?,0)r 

QUITcRECOOEi; 

FINIS: 



Figure 5-3. FCARD Intrinsic Example (3 of 3) 
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RESOURCE MANAGEMENT 



SECTION 



VI 



Within MPE, any element that can be accessed by your program is regarded as a resource. Thus, a 
resource can be an input/output device, file, program, subroutine, procedure, code segment, or the 
data stack. 

Occasionally, you may want to manage a specific resource shared by a particular set of jobs or 
processes, so that no two of these jobs or processes can use the resource at the same time. To 
accomplish this type of resource management on either the inter-job (or session) or inter-process 
level, the jobs or processes involved must mutually cooperate. For example, if job B must not access 
a particular file when job A is using it, both jobs should include provisions for a hand-shaking 
arrangement overseen by MPE when these jobs are being executed concurrently. Under this arrange- 
ment, when job A has exclusive access to the file and job B attempts to access the same file, this 
access will be denied. Job B will be suspended until job A releases its exclusive access. Then, job B 
can resume execution and access the file. 

NOTE 

It is important to realize that as long as job B is suspended, it 
not only cannot access the file — it cannot perform any 
operations. 

On either the inter-job or inter-process level, the hand-shaking arrangement is based upon an 
arbitrary resource identification number (RIN) made available to users (at the inter-job level) or 
assigned to the job (at the inter-process level). Within their jobs (or processes), the cooperating 
programmers relate a RIN to a particular resource through the structure of the statements making 
up each job (or process). When a job (or process) seeks exclusive access to a resource, it requests 
MPE to lock the RIN associated with this resource. This request is granted only if no other job or 
process has already locked the RIN. Otherwise, the requesting process is suspended until the RIN is 
released. When it is finished with the resource, the job (or process) requests MPE to unlock the RIN 
so that other jobs or processes can lock it. 

A RIN is not a physical entity. Furthermore, it is not logically assigned to any resource. The 
association between a RIN and a resource is accomplished only by tue structure Os. me Suauernen^ 
within the job or process using the RIN. The resource identification number is always known to 
MPE, but its meaning (the resource with which it is associated) is not. For this reason, all cooperat- 
ing programs must specify what RIN is associated with what resource through their statements. 

Processes run by users having only the Standard MPE Capabilities can lock only one global RIN at a 
time. But processes run by users having the Multiple RIN Optional Capability can lock more than 
one global RIN at a time. In doing so, however, such users must be careful to avoid deadlocking, 
where two or more suspended processes cannot be resumed because they are mutually blocked. 
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INTER-JOB LEVEL (GLOBAL) RIN'S 

The RIN's used at the unrelated process level are called global RIN's. Global RIN's are used to 
exclude simultaneous access of a resource by two or more processes. Each global RIN is a positive 
integer unique within MPE. Global RIN's are acquired and released through MPE commands, and 
locked and unlocked through MPE intrinsics. 

ACQUIRING GLOBAL RIN'S 

Before any users can mutually engage in resource management through a RIN, one of these users 
must request the RIN and assign it a RIN password that enables all who know the password to lock 
the RIN. This is done by entering the :GETRIN command: 

:GETRIN rinpassword 

where 

rinpassword is a password required in the intrinsic that locks the RIN. It is a string 

of up to eight alphanumeric characters beginning with a letter. 
(Required parameter.) 

The :GETRIN command is typically entered during a session. As a result of the command, MPE 
makes a RIN available for use and displays the RIN number in this format: 

RIN: rin 

where 

rin is the RIN number. 

The user who entered the :GETRIN command can use the RIN number to lock and unlock the RIN 
in the current session, or in future jobs and sessions. The RIN number and password also are passed 
on to other users to permit them to lock and unlock the RIN in their jobs and sessions. All users 
pass the RIN number to the intrinsics that lock and unlock the RIN, as a reference parameter in 
the intrinsic calls. These users can continue to use the RIN until the user who issued the :GETRIN 
command for this RIN releases the RIN. 

NOTE 

MPE regards the user who issued the :GETRIN command as 
the owner of the RIN assigned. This means that only this user 
may release the RIN. 

The total number of RIN's that MPE can allocate is specified when the system is configured, and 
in no case can exceed 1024. 

See the MPE Commands Reference Manual for a further discussion of the :GETRIN command. 
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RELEASING GLOBAL RIN'S 

The owner of a global RIN (the user who issued the :GETRIN command to acquire the RIN) can 
de-allocate the RIN, returning it to the RIN pool managed by MPE. Only the owner can de- 
allocate the RIN. 

The RIN is de-allocated with the :FREERIN command 

:FREERIN rin 

where 

r i n is the number of the RIN to be de-allocated. (Required parameter.) 

See the MPE Commands Reference Manual for a further discussion of the :FREERIN command. 

LOCKING AND UNLOCKING GLOBAL RIN'S 

Any global RIN assigned to a group of users can be locked by one process at a time with the LOCK- 
GLORIN intrinsic. Once a RIN is locked, any other processes that attempt to lock this RIN are 
suspended. 

In order to lock a global RIN, you must know both the RIN number returned by MPE when the 
RIN was acquired with the :GETRIN command, and the password which was specified in the 
rinpassword parameter of the :GETRIN command. If you are a user with only the Standard MPE 
Capability, you can lock only one global RIN at a time. 

The LOCKGLORIN intrinsic is useful in applications where locking an entire file is not desirable 
because it may inconvenience other users. For example, if several users are trying to access and up- 
date a large file simultaneously, any one user who succeeds in locking the file suspends the other 
users' processes until the file is unlocked. The LOCKGLORIN intrinsic, however, can be used to 
lock a portion of such a file so that the chance of inconveniencing the other users is lessened. 

UNLOCKGLORIN does not check whether the rinnum parameter specifies the most recently 
locked global RIN. When global RIN's are locked and unlocked in any order by concurrent pro- 
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........ - - I 

cesses, deadlocks can occur. An eiiective way 10 avoia aeaaiocKs is w assign an uiunuig ui "n, s 

which is used by all processes locking them. 

Figure 6-1 contains a program which uses the LOCKGLORIN and UNLOCKGLORIN intrinsics. 
The program allows a user to iock four records, as a RIN, in a file so that a record can be update^ 
without any chance of some other user updating the same record simultaneously. Additionally, 
the other users are not suspended when attempting to access and update records elsewhere in 
the file. 

The file used in the example (see below) contains 20 records and therefore five contiguous RIN's 
have to be acquired (there are four records per RIN) before the program is run. This is accomplished 
by entering :GETRIN commands as follows: 

:GETRIN BOOKRIN 

where BOOKRIN is specified as the rinpassword parameter. BOOKRIN is the password which is 
used in the program to lock the RIN (see statements 6 and 36 in figure 6-1). 
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NO, ERRORS=000; 




PROCESSOR TIME= 


0:00 



SCONTROL USLINIT 
BEGIN 

BYTE ARRAY INPUTCO :5 ):=" INPUT "; 

BYTE ARRAY OUTPUT(0 :6) :="OUTPUT "; 

BKTE ARRAY NAMECO: 8 ) : ="bOOKFILE "; 

-Mm mxM \ 9m&mmii^i**wGMm »*: 

INTEGER IN,OUT,BOOK,LGTH,ACCNO,RIN; 

LOGICAL DUMMY, COND:=TRUE; 

ARRAY BUFRC0:35); 

BYTE ARRAY BBUFR(*)=BUFR; 

ARRAY HEAD(0:13):="LIBRARK INFORMATION PROGRAM."; 

ARRAY REOUEST(0:7):=%6412, "ACCESSION NO; "; 

ARRAY CHANGEC0:9):=" NEW LOCATION: "; 

mmmw- «r«BAS£-2 : *- REeos*i>ER* : Pi : «s4, .nimmm; 

DEFINE CCL =IF < THEN QUIT*, 
CCNEsIr <> THEN QuiT#; 

INTRINSIC F0PEN,FREAD,FWRITE,FC0NTR0L,FREADDIR,FWRITED1R, 
LOCKGLORIN,UNLOCKGLOR IN, QUIT, BINARY; 



«END OF DECLARATIONS>> 

IN:=K0PEN(INPUT,%45); CCL(l); 
OUT: =F0PEN( OUTPUT, %414); CCL(2); 
BOOK:=FOPEN(NAME,%5,%304); CCLC3); 
FWRITECOUT, HEAD, 14,0); CCNEC4); 
LOOP: 

FWRITEC OUT, REQUEST, 8. %320); CCNEC5); 
LGTH:=FREAD(IN,BUFR,-10); CCNE(6); 
IF LGTH=0 THEN GO EXIT; 
ACCNO:=BlNARY(BBUFR,LGTH); 
IF <> THEN GO LOOP; 

RIN:=RINBASE+(ACCNO/RECDS'PER'RIN); 

IF N0T(RINBASE<=R1N<=MAXRIN) THEN GO LOOP; 

.mmmxmmtwm ;c«*tppAsswD > i 

FREADDIR(BOOK,BUFR,36,DOUBLE(ACCNO)); CCLC7); 
IK > THEN GO AGAIN; 
FWRITE(OUT,BUFR,36,0); CCNE(8); 
FWRI TEC OUT, CHANGE, 10,%320) J CCNEC9); 

BUFRC19):=" "; 
MOVE BUFRC20):=BUFR(19),(16); 
LGTH : =FREAD ( IN , BUFR ( 1 9 ) , 1 7 ) ; CCNE ( 1 ) ; 
IF LGTH>0 THEN 
BEGIN 

FWRITEDIR(BOOK,BUFR,36,DOUBLE(ACCNO)); 
CCNEC11); 
END; 
FCONTROLCBOOK,2,DUMMY); CCL (12); 
AGAIN: 

:..o«*iioe:«siiRri( :: Ri»^;r^c : «Eii3) ;: f : : ■ . 

GO LOOP; 
EXIT:END. 
%021; SECONDARY DB STORAGE=%00124 

NO, WARNINGS=0O0 
:03; ELAPSED TIME=0:00:10 



<<SSTDIN» 
<<SSTDLIST>> 
«OLD DISC FILE>> 
<<PROGRAM ID>> 

«REQST BOOK NUMBR» 
<<INPUT NUMBER>> 
«NO INPUT-EXIT>> 
«CONVERT NUMBER>> 
«IF BAD TRY AGAIN>> 

<<C0MPUTE RIN NO,>> 
<<B0UNDS CHECK RIN>> 

■:<<yDCK Ei :FrLE:. SUBS£T» 

<<READ BOOK DATA>> 
<<EOF - TRY AGAIN>> 
<<DISPLAY DATA» 
<<REQST A CHANGE>> 



<<BLANK OLD LOCN>> 
<<READ NEW LOCN» 
<<NEW LOCN ENTERED>> 

<<MODIFY THE FILE>> 
<<CHECK FUR ERROR>> 

<<FORCE RECD POST>> 

«U SLOCK: SUBSET** 
<<CONTINUE>> 



Figure 6-1. Using the LOCKGLORIN and UNLOCKGLORIN Intrinsics 
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TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 



THE BORROWERS LOCN 

ALICE IN WONDERLAND LOCN 

PETER PAN LOCN 

JUNGLE BOOK LOCN 

MARY POPPINS LOCN 

TOM SAWYER LOCN: 

TREASURE ISLAND LOCN 

A CHRISTMAS CAROL LOCN 

HOUSE AT POOH CORNER LOCN 

THE WIZARD OF OZ LOCN 

SLEEPING BEAUTY LOCN 

TALES OF MOTHER GOOSE LOCN 

AESOP'S FABLES LOCN 

KIDNAPPED LOCN 

OLIVER TWIST LOCN 

DR. DOLITTLE LOCN 

WHEN WE WERE VERY YOUNG LOCN 

H.M.S. PINAFORE LOCN 

WORLD BOOK ENCYCLOPEDIA LOCN 

COLLEGIATE DICTIONARY LOCN 



AVAILABLE 

AVAILABLE 
AVAILABLE 
AVAILABLE 
AVAILABLE 
AVAILABLE 
AVAILABLE 
AVAILABLE 
AVAILABLE 
AVAILABLE 
AVAILABLE 
AVAILABLE 
AVAILABLE 
AVAILABLE 
AVAILABLE 
AVAILABLE 
AVAILABLE 
AVAILABLE 
AVAILABLE 



The orogram in figure 6-1 establishes the RIN number limits 2 and 6 (see statement number 14), 
thus using only RIN numbers 2, 3, 4, 5, and 6. MPE returns the RIN number assigned each time 
the iGETRIN command is entered. Because MPE does not always assign RIN numbers in sequence, 
however, it may be necessary to enter more than five :GETRIN commands in order to acquire the 
five contiguous RIN's 2, 3, 4, 5, and 6. Extra RIN's can be released with the :FREERIN command. 

The statements 

FWRITE(OUT,REQUEST,8,%320);CCNE(5); 

request a book number from the user and perform a condition code check. Note that in statement 
number 16, CCNE has been defined as 

IFOTHENQUFTJ; 

This eliminates the need to repeat the entire statement at every point in the program where such a 
j;+i. — „~A a ^^.v ic mnnirori TnetpnH t.Vip statement CCNE and an arbitrary number, (5) in 

this case, can be used. 

The book number is read with the statement 

LGTH:=FREAD(IN,BUFR,-10); 
and converted to a binary value with the statement 

ACCNO:=BINARY(BBUFR,LGTH); 
The RIN number to be locked is computed with the statement 

RIN:=RINBASE+(ACCNO/RECDS'PER'RIN); 
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RINBASE and RECDS'PER'RIN have been equated to 2 and 4, respectively (see statement number 
14). Thus, if book number 3 is entered by the user, the RIN number to be locked would be 
computed as RIN number 2, as follows: 

RIN = 2 + (3/4) 

= 2 + (integer division) 

The record specified by the book number is displayed for the user and the change ("NEW 
LOCATION: ") is requested. The existing location information is filled with blanks with the 
statements 

BUFR(19):=" "; 

MOVE BUFR(20):=BUFR(19),(16); 
The new location is entered and read with the statement 

LGTH:=FREAD(IN,BUFR(19),(17); 
and the record is updated with the statement 

FWRITEDIR(BOOK,BUFR,36,DOUBLE(ACCNO)); 
The statement 

FCONTROL(BOOK,2,DUMMY); 

is used in case the file which has been opened is a buffered file. This statement insures that the 
process' buffers are posted to the disc before the RIN is unlocked. 

Note that in a program of this kind, it is important that the number of records per block and the 
number of records per RIN are the same. The RIN must contain a complete block of records. 

The statement 

UNLOCKGLORIN(RIN); 

unlocks the RIN before the loop is repeated. When the user enters a new book number, a new RIN 
number will be computed and that RIN number will be locked. 

When a carriage return is entered, signifying no input, the program terminates. 

The results of running the program and the updated condition of the library file are shown below. 

INTER-PROCESS (LOCAL) LEVEL RIN'S 

The RIN's used at the inter-process level are called local RIN's. These RIN's are used to exclude 
simultaneous access of a resource by two or more processes within the same job. Each RIN number 
is a positive integer that is significant only with respect to different processes within that job. 
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: RUN LIBIN 

LIBRARY INFORMATION PROGRAM. 

ACCESSION NO: 3 

TITLE: JUNGLE BOOK LOCN: AVAILABLE 

NEW LOCATION: FACULTY LOAN - DR. SCHWARTZ 

ACCESSION NO: 10. 

TITLE: SLEEPING BEAUTY LOCN: AVAILABLE 

NEW LOCATION: LOANED CARD# 451, DUE JUNE 6 



ACCESSION NO: 3 
TITLE: JUNGLE BOOK 
NEW LOCATION: 



LOCN: FACULTY LOAN - DR. SCHWARTZ 



ACCESSION NO: 9 

TITLE: THE WIZARD OF OZ LOCN: AVAILABLE 

NEW LOCATION: INTERLIBRARY LOAN - UNIV. OF OZ 



ACCESSION NO: 3. 
TITLE: JUNGLE BOOK 

NEW LOCATION: AVAILABLE 

ACCESSION NO: return 

END OF PROGRAM 



LOCN: FACULTY LOAN - DR. SCHWARTZ 



TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

TITLE 

i X 1 i-j^. 

TITLE 
TITLE 



THE BORROWERS LOCN 

ALICE IN WONDERLAND LOCN 

PETER PAN LOCN 

JUNGLE BOOK LOCN 

MARY POPPINS LOCN 

TOM SAWYER LOCN 

TREASURE ISLAND LOCN 

A CHRISTMAS CAROL LOCN 

HOUSE AT POOH CORNER LOCN 

THE WIZARD OF OZ LOCN 

SLEEPING BEAUTY LOCN 

TALES OF MOTHER GOOSE LOCN 

AESOP'S FABLES LOCN 

KIDNAPPED LOCN 

OLIVER TWIST LOCN 

DR. DOLITTLE LOCN 

WHEN WE WERE VERY YOUNG LOCN 

tr m c- or MAtrnotr T.finN 

WORLD BOOK ENCYCLOPEDIA LOCN 

COLLEGIATE DICTIONARY LOCN 



AVAILABLE 

AVAILABLE 

AVAILABLE 

AVAILA3LE 

AVAILABLE 

AVAILABLE 

AVAILABLE 

AVAILABLE 

AVAILABLE 

INTERLIBRARY 

LOANED CARD# 

AVAILABLE 

AVAILABLE 

AVAILABLE 

AVAILA3LE 

AVAILABLE 

AVAILA3LE 

AVAILABLE 

AVAILABLE 

AVAILABLE 



LOAN - UNIV. OF 
451, DUE JUNE 6 



OZ 
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Local RIN's are assigned, managed, and released with the GETLOCRIN, LOCKLOCRIN and 
FREELOCRINintrinsics. 

ACQUIRING LOCAL RIN'S 

Just as global RIN's must be acquired by users before they can be used in jobs, local RIN's must be 
acquired by a job before they can be used by processes within the job. This is done with the 
GETLOCRIN intrinsic. For example, the intrinsic call below would acquire six local RIN's: 
GETLOCRIN(6); 

The RIN's acquired are identified by RIN numbers 1 through 6. Note that Multiple RIN capability 
is not required; it is the user's responsibility to avoid deadlocks. 

LOCKING AND UNLOCKING LOCAL RIN'S 

Any local RIN assigned to a job can be locked, by one process at a time, by issuing the LOCKLOC- 
RIN intrinsic call within that process. When this is done, other processes within the job that attempt 
to lock this RIN are suspended until the locked RIN is released. 

For example, to lock RIN number 6 (acquired with the GETLOCRIN intrinsic) unconditionally, the 
following intrinsic call could be used: 

LOCKLOCRIN( 6,COND) ; 

The logical word COND = TRUE for unconditional locking. If COND = FALSE, locking will take 
place only if the RIN is immediately available. 

To unlock this same RIN, the following UNLOCKLOCRIN intrinsic call could be used: 
UNLOCKLOCRIN(6); 

The above call makes RIN number 6 available for locking by other processes in the job. The highest 
priority process suspended because this RIN was locked is now activated. 

To illustrate how the LOCKLOCRIN and UNLOCKLOCRIN intrinsic calls are used, consider two 
processes (a father process and its son) within a job: 



FATHER PROCESS 



SON PROCESS 



LP:=FOPEN (LIN, . . .); 

GETLOCRIN (3); 

FWRITE (LP, . . .); 

LOCKLOCRIN (1, TRUEVAL); 
CREATE (DESCEND, . . .). 



LP:=FOPEN(LIN, ...); 

LOCKLOCRIN (1, TRUEVAL); 
FWRITE (LP, . . .); 
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FWRITE (LP, . . .); 



UNLOCKLOCRIN (1); 



FWRITE (LP, . . .); 



UNLOCKLOCRIN (1); 



Suppose that the father process and its son wanted to use RIN (1) to manage a line printer 
(designated by LP) so that the son process could not use the printer at any time that it was being 
used by the father process. This could be done as shown in the above coding. When the father 
process first references LP, the son process is not yet created and the printer need not be locked. 
However, just prior to creating the son, the father process locks the RIN covering the printer. The 
father issues all of its print requests before unlocking the printer. Before the son process accesses 
the printer, it tries to lock it, fails, and is suspended. As soon as the father unlocks the printer, the 
son process locks it, and issues print requests. 

IDENTIFYING LOCAL RIN OWNERS 

LOCRINOWNER allows you to identify at any given time the PIN of the process that has a 
particular local RIN locked. This information can be useful, for example, in situations where father 
and son processes are being synchronized through calls to the ACTIVATE and SUSPEND intrinsics. 
(See descriptions of ACTIVATE and SUSPEND in the Process Handling Capability Section) 

Consider the following example in which a father process acts as a monitor for several son processes. 
The father waits SUSPENDed at the top of its loop to be ACTIVATEd by any son. When 
ACTIVATEd, the father locks a RIN to synchronize its communication with the son. LOCRIN- 
OWNER is used to determine the PIN of the son that ACTIVATEd the father, since that son will 
have the "whichson" RIN locked. The father can then do whatever processing it needs to do. The 
father finaUy ACTIVATES the son that ACTIVATEd the father process and SUSPENDS, releasing 
the synchronization RIN and waiting for the next son to ACTIVATE it again. 
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«Example of Process Synchronization with LOCRINOWNER» 

equate whichsonrin = 1, 

synchrin = 2, 

waitforfather = 1, 

waitforson = 2; 



« father process» 



soncount : = 0; 

while soncount <= maxsons do 

begin 

SUSPEND (waitforson, synchrin); 

LOCKLOCRIN (synchrin); 

owner : = LOCRINOWNER (whichsonrin); 



«son process» 



LOCKLOCRIN (whichsonrin); 
LOCKLOCRIN (synchrin); 
ACTIVATE (father); 
SUSPEND (waitforfather, synchrin); 
UNLOCKLOCRIN (whichsonrin); 



soncount : = soncount + 1; 
ACTIVATE (owner); 
end; 



FREEING LOCAL RIN'S 

To free all local RIN's currently reserved for your job, the FREELOCRIN intrinsic is called, as 
follows: 

FREELOCRIN; 
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PROCESS-HANDLING CAPABILITY 



SECTION 



VII 



All user and system programs under MPE are run on the basis of processes — which are the basic 
executable entities in the operating system. Processes are invisible to a programmer with standard 
capabilities who accesses MPE. This programmer has no control over processes or their structure; 
for him, MPE automatically creates, handles, and deletes all processes. Users with certain optional 
capabilities, however, can interact with processes directly. One of these optional capabilities is the 
Process-Handling Optional Capability, discussed in this section. 

The Process-Handling Capability, assigned and used independently of the other optional capabilities, 
allows you to 

Create and delete processes. 

Activate and suspend processes. 

Manage communications between processes. 

Change the scheduling of processes. 

Obtain information about existing processes. 

These operations can be very useful to you. For instance, they allow you to have several independent 
processes running concurrently on your behalf, all communicating with one another. 

PROCESSES 

A process is an independent entity that can be run within MPE: processes are run on behalf of 
users and on behalf of the operating system. Many processes can be running concurrently. The 
design of MPE is process-oriented: the system deals exclusively with processes (except for interrupt 
routines and some very central and specialized system functions). 

A process consists of a private data area (the stack) used only by this process, a Process Control 
Block (PCB) that defines the process, and instructions in a code segment that the process is to 

execute. INOte mat uoue segments aic uscu uy puv,cijocD, u>" mm*-** vj v^v.1^, *~™ "*»j! — -™ — — ~, 

be shared by many processes. 

When a user enters MPE, a process is created for him. This process is called a Job Main Process 
(JMP) in batch mode or a Session Main Process (SMP) in time-share mode. The process is linked 
into the Command Interpreter which then proceeds to handle user commands. 

Every process known to MPE is identified by a number called the Process Identification Number 

/ivrvr\ n/f„„+ „„„+,.~l ;^ A/TOTT io noTriarl ,-.11+ q+ +Vio nrnivKt loirol A nmr-pis ran run flnv kind of code 

(programs, procedures, private code, sharable code, and so forth) and one of the main elements 
needed to establish a new process is a starting address (that is a program label). From this address on, 
the life of the process follows the sequence of the code until its deletion. 
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The Progenitor is the first process established during the initialization phase of MPE. It is the 
responsibility of the Progenitor, using a set of configuration data specified at system configuration 
time, to create its son processes. These processes are defined as system processes and are used to 
perform parallel functions on behalf of the system. Such processes may include I/O processes, etc., 
and in particular the User Controller Process (UCOP). All these processes may, if required, have 
their own structure of descendents. 

Whereas the Progenitor is the ancestor of all processes in MPE, including system processes, the User 
Controller Process is the ancestor of all User Processes currently in existence. The UCOP is thereby 
the root of the user process Tree Structure. The sons of the UCOP are called (User) main processes. 

The father/son relationship between processes is used mainly to maintain control from top to 
bottom everywhere in the structure. Roughly speaking, a father is always held "responsible" for 
what happens to its son: creation, deletion and other special actions. 

ORGANIZATION OF USER PROCESSES 

When you log on yourself, a main process is created for you by UCOP. According to the mode of 
access, the main process can be one of the two types: 

— Job Main Process ( JMP) 

— Session Main Process (SMP) 

Such a distinction results from the different kinds of control that the system provides for those two 
separate entities: job is associated with a batch type of access, while session is for interactive access. 

As soon as a given signal is received by UCOP, a JMP or SMP is created (depending upon the origin 
of the signal). The starting address of the JMP or SMP is the Command Interpreter and once the 
user is validated, the main process is free to recognize any command. 

PROCESS SUBSTATES 

During its life span (i.e., between its creation and its deletion), a process finds itself in different 
substates according to its past and present history as well as its present requirements. Only two of 
these may be controlled by users: active substate and suspended substate. 

An active process is run by the CPU until it suspends itself, terminates, or is killed. 

A suspended process is not run by the CPU as long as it stays in this substate. In other words, a 
suspended process is waiting for some kind of a signal which will activate it. When it suspends 
itself, a process may specify the origin of its next activation. 

You can control the termination of one of your processes. The termination destroys the process 
and all its descendents and resets the links of the remaining processes for the session or job. 

PROCESS TO PROCESS COMMUNICATION 

MPE provides a means for processes to communicate between themselves. 

The sending or receiving of information is restricted to either an upward or downward path; thus 
such communication is allowed only between father and son, and only one transfer is allowed in 
either direction at any given time. 
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This method results from the fact that the father is solely responsible for both the existence and 
actions of his sons. The father created his sons and knows their identification in the process structure; 
he can, therefore, reference them at any time. The sons, however, only know their father by the 
default identification "father". 

CREATING AND ACTIVATING PR0 CESSES 

From within any running process, you can programmatically request the creation of a son process 
with the CREATE intrinsic. The CREATE intrinsic loads the program to be run by the new process 
into virtual memory, creates the new process as the son of the calling process, initializes its data 
stack, schedules the process, and returns its Process Identification Number (PIN) to the calling 
process. 

Once a process is created, it must be activated with the ACTIVATE intrinsic in order to run. When 
a process is activated, it may suspend the process that activated it, then run until it is suspended or 
deleted. A newly-created process can be activated only by its father. A father process that has been 
suspended when a son process was activated can be reactivated automatically when the son process' 
execution ends, if a bit has been set in the flags parameter of the CREATE intrinsic. A process that 
has been suspended with the SUSPEND intrinsic (see page 7-8) can be reactivated by its father or 
any of its sons, as specified in the susp parameter of the SUSPEND intrinsic. 

Figure 7-1 contains a program wnicn illustrates tne biuiiiifi miu rtvinma """"»>*• 

The statement 

FWRITE(OUT,REQST,9,%320); 
requests the user to enter the program file name which is to be created and activated. 
The statement 

LGTH:=FREAD(IN,NAME,-26); 

reads the name input by the user on $STDIN and stores the name in the array NAME. In order to 
be used in the CREATE intrinsic, the string in the array NAME must be specified in a byte array; 
thus the byte array BNAME is equivalenced to NAME in statement number 8 in the program. Add- 
itionally, the string must be terminated by a blank and the statement 

BNAME(LGTH):=%40; 
enters the ASCII code for a blank character to the end of the string in BNAME. 
Next, the program displays the message 

CREATE PROCESS 
and calls the CREATE intrinsic with the statement 

CREATE(BNAME„PIN„1); 
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PAGE 0001 HEWLETT-PACKARD 321OOA.05.1 SPL/3000 



HON, DEC 1, 1975, 2:09 PM 



00001000 
00002000 
00003000 
00004000 
00005000 
00006000 
00007000 
00008000 
00009000 
00010000 

ooouooo 

00012000 

00013000 

00014000 

00015000 

00016000 

00017000 

00018000 

00019000 

00020000 

00021000 

00022000 

00023000 

00024000 

00025000 

00026000 

00027000 

00028000 

00029000 

00030000 

00031000 

00032000 

00033000 

00034000 

00035000 

00036000 

00037000 

00038000 

00039000 

00040000 

00041000 

00042000 



00000 
00000 
00000 
00004 
00005 
00005 
00011 
00011 

00011 1 
00007 1 
00010 1 
00010 1 
00010 1 
00010 1 
00010 1 
00010 1 
00010 1 
00010 1 
00010 1 
00007 1 

00012 1 
00022 1 
00025 1 
00025 1 
00025 
00032 



1 
1 
00035 1 



SCONTKOL USLINII 
-BEGIN 

BYTE ARRAY INPUTCO ! 5 ) : =" INPUT "; 

BYTE ARRAY OUTPUTCO : 6 ) :="OUTPUt' " ; 

INTEGER IN,OUT,LGTH,PIN; 

ARRAY REQSTC0:8):=%6412, "PROGRAM KILE = »; 

ARRAY NAME(0:13); 

BYTE ARRAY BNAME(»)=NAME; 

ARRAY CRMSG(0!6):="CREATE PROCESS"; 

ARRAY ACTMSG(0:7):="ACTIVATE PROCESS"! 

DEFINE CCL=IF < THEN QU1T#, 

CCG=IF > THEN QUIT#, 

CCNE=IF <> THEN QU1T#; 

INTRINSIC FOPEN,FREAD,FWRITE, CREATE, ACTIVATE, QUIT; 
«END OF DECLARATIONS» 



IN!=F0PENCINPUT,%45); 
CCL(l); 

0UT:=F0PEN(0UTPUT,%414,1)' 
CCLC2); 



00043 1 
00046 1 
00053 1 
00056 1 
00056 1 
00063 1 
00066 1 
00076 1 
00101 1 
00101 1 
00106 1 
00111 1 
00115 1 
00123 1 
00130 1 
PRIMARY DB STORAGE= 
NO. ERRORS=000; 
PROCESSOR TIME=0:00 



NEXT: 

fWfUTEJOUT,R£OST,»,%32Q); 
CCtfEmj 

LGTH:*FMs;M>UN.,KAME,-2«j 
CCNKCOf 

if t,ci:a*«3 rm:$ a? mixi 

FWR1TE(OUT,CRMSG,7,0); 

CC»£tS)> 

CB KATE C V. K,«:t ,,»Ti(,,ih 

CCU6): 

>i»Mlft(.lU7,ACTMSG,°,Oj; 
crr.KC/;; 

ccLte)! ecsmi 

EXIT:END. 

%013; SECONDARY DB STORAGE=%00055 
NO, WARNINGS=000 
04 s ELAPSED TIME=0:00:51 



<<SSTDIN>> 
«CHECK FOR ERROR» 
<<SSTDLIST>> 
<<CHECK FOR ERROR» 

«PLOUFhT PP'JGRAM MU "&•>£» 
«CHf*CK HM i:RFciP>> 

«tmui ri\£ nk¥,E» 

«CKKCK FOK ESRQft» 

«skt :r mumsg ulank» 

«Ckl-ATE MfSSAGt» 

«chsck fun t:«aos» 

«CUKAU FRCCF.Si>i 

<*ACnVATE ME&5AGE» 
«XC^EC*. fett fcfft&«» 
«ACTIVAT£ PK»C£JS>> 
<<check rem ERR0R» 



Figure 7-1. Using the CREATE and ACTIVATE Intrinsics 
The following parameters were specified in the above intrinsic call: 



progname 
entry name 



Specified by BNAME, which contains the name entered by the user. 

Omitted. The primary entry point of the created process is specified 
by default. 



pin 



The Process Identification Number (PIN), to be used by the ACTIVATE 
intrinsic, is returned to the word PIN. 



param 
flags 
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Omitted. A word filled with zeros is specified by default. 

1, which specifies that this (the father) process will be reactivated 
automatically by MPE when the created process' execution ends (bit 
15 = 1). 



All other parameters are omitted in the CREATE intrinsic call. 
The statement 

FWRITE(OUT, ACTMSG,8,0); 
displays the message 

ACTIVATE PROCESS 
and the statement 

ACTIVATE(PIN,2); 

calls the ACTIVATE intrinsic to activate the process. The following parameters were specified: 

pin Specified by PIN, which contains the Process Identification Number 

of the process to be activated, as returned to the CREATE intrinsic by 
the system. 

susp 2. When susp is specified, the calling process is to be suspended when 

the called process is activated. When 2 (bit 14 = 1) is specified, as in this 
call, the suspended calling process expects to be reactivated auto- 
matically by MPE when this son process ends execution. If susp was 
not specified, the calling (father) process will not be suspended when 
the called process is activated. 

Shown below is an example of running the program (named PROC) listed in figure 7-1. 



:RUN PROC 



PROGRAM FILE = SPL.PU3.SYS 
CREATE PROCESS 
ACTIVATE PROCESS 

PAGE 33251 >P32 1 33A .0 5. 1 



> fC0NTR0L USLIN1T 
> BEGIPJ 

> ARRAY MSG(3;12);="* TEST PROCESS EXECUTING *"; 

> INTRINSIC PRIMTJ 

> PRINT <MSGjI3*3)J 
> END. 

PRIMARY DB STQRAGE=%33 1 ; SECONDARY D3 STORAGE=%003 1 5 
NO. ERR0RS=333; NO. WARNINGS =030 

PROCESSOR TIME=3 :08 :02l 
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PROGRAM FILE = SEGDVR.PUB.SYS 

CREATE PROCESS 

ACTIVATE PROCESS 

SEGMENTER SUBSYSTEM (C.0) 

- USL SOLDPASS 

- PREPARE SNEWPASS 

- EXIT 

PROGRAM FILE = SOLDPASS 

CREATE PROCESS 

ACTIVATE PROCESS 

* TEST PROCESS EXECUTING * 

PROGRAM FILE = return 

END OF PROGRAM 



When SPL.PUB.SYS is entered in response to the PROGRAM FILE = request, the program displays 

CREATE PROCESS 

ACTIVATE PROCESS 

then suspends itself and the SPL compiler subsystem is accessed. (This process has been created and 
activated because of the SPL.PUB.SYS response by the user.) 

A short program is entered from the terminal and the SPL compiler is exited, reactivating PROC at 
the statement following the ACTIVATE intrinsic call, and causing the PROGRAM FILE = message 
to be displayed again. 

The response 

SEGDVR.PUB.SYS 

causes PROC to create and activate the Segmenter Driver (a programmatic entry point to the Seg- 
menter subsystem). The Segmenter displays 

SEGMENTER SUBSYSTEM (CO) 

and a prompt character (-). 

The small program written in SPL and compiled into the USL file $OLDPASS (the default USL 
file since a USLfile parameter was not included in the SEGDVR.PUB.SYS response) is identified 
with the 

-USL $OLDPASS 
Segmenter command. 
The next command 

-PREPARE $NEWPASS 
prepares the SPL program and the Segmenter is exited with the 

-EXIT 
command. 
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Once again, PROC is reactivated and requests a program file to be created and activated. The response 
($OLDPASS) causes the compiled and prepared program written in SPL to be created and activated. 

This program executes, displays 

*TEST PROCESS EXECUTING* 

then ends execution, reactivating PROC. 

A carriage return, signifying no input, is entered in response to the PROGRAM FILE = request and 
the program terminates. 

The example below uses PROC to create and activate a duplicate of itself. 
:RUN PROC 



PROGRAM FILE = PROC 
CREATE PROCESS 
ACTIVATE PROCESS 

PROGRAM FILE = PROC 
CREATE PROCESS 
ACTIVATE PROCESS 

PROGRAM FILE = returnl 

PROGRAM FILE = return2 

PROGRAM FILE = return3 

END OF PROGRAM 



When PROC is entered in response to the PROGRAM FILE = request, the calling process (PROC) 
creates a duplicate of itself and activates this process (for clarity, call this PROC1). This process 
executes and requests a file name. The user enters PROC again, causing yet another duplicate 
(call this one PROC2) to be created and activated. At this point, PROC is suspended: it has 
created and activated a duplicate process. The duplicate process (PROC1) has, in turn, created and 

i. _ _i - j i;„i._ „* :j.„„i* /r>T>/~>no\ TVmc ;+ qIc/-, ic oncnonHoH Thp t.hirrl nroness (PROC2^ 

acuvaieu a uupiiuate ui luacu. ^ nuv^;. au^o, *» **+w **. — r — - jr -- 

executes and displays 
PROGRAM FILE = 

A carriage return (see returnl in the example) causes this process to stop executing and control 
returns to PROC1. 
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PROC1 displays 

PROGRAM FILE = 

Again, a carriage return (return2 in the example) causes this process to stop executing and control 
returns to PROC. 

PROGRAM FILE = is displayed once more, this time by the original process. Carriage return3 
causes PROC to stop executing and control returns to the session main process, which displays 

END OF PROGRAM 



SUSPENDING PROCESSES 

A process can suspend itself with the SUSPEND intrinsic. When this is done, the process relinquishes 
its access to the central processor until reactivated by an ACTIVATE intrinsic call. When it suspends 
itself, the process must specify the anticipated source of this ACTIVATE call (its father or son 
process). When the process is reactivated, it begins execution with the instruction immediately 
following the SUSPEND intrinsic call. The SUSPEND intrinsic also can release a local Resource 
Identification Number (RIN) when the process is suspended by specifying the RIN number as a 
parameter in the intrinsic call. 

The intrinsic call 

SUSPEND(3,RINNUM); 

would cause the process to suspend itself and release the local RIN specified by RINNUM The 
parameter 3 (bits 14 and 15 = 11) specifies that the process expects to be reactivated by either its 
father or one of its sons. 

DELETING PROCESSES 

A process can request the deletion of itself with the TERMINATE intrinsic or the deletion of any 
of its sons with the KILL intrinsic. When this is done, all code and data segments in the process 
and all resources owned by the process, are released; all temporary files opened by the process are 
closed; and finally, the Process Identification Number (PIN) is released. When a process is deleted 
MPE also automatically deletes all descendents of that process, as shown in figure 7-2 Within a 
process tree structure, the newest generations are deleted first. Within each generation, processes 
are deleted in the order of their creation. 

In a job or session main process, the TERMINATE intrinsic is invoked automatically by detection 
of an end-of-job/session condition. This intrinsic removes the job or session from the system. 

The form of the TERMINATE intrinsic call is 

TERMINATE; 
The form of the KILL intrinsic call is 

KILL(PIN); 

Where PIN contains the Process Identification Number of the son process to be deleted. 
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FIRST (OLDEST) 
GENERATION 



SECOND 
GENERATION 



THIRD 
GENERATION 



FOURTH (NEWEST) [ pR0CESS 5 ] 
GENERATION \ J 




(WHEN PROCESS 2 IS DELETED, THE FOLLOWING STRUCTURE RESULTS.) 



FIRST 

UCIMtnH I I WIM 



SECOND 
GENERATION 




Figure 7-2. Process Deletion 
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INTERPROCESS COMMUNICATION 

You can direct the communication of information between processes. This information transfer, 
however, is restricted to upward or downward paths through the process tree structure, so that 
any process can communicate only with its father or sons. Between any father/son pair, only one 
such transfer is allowed at any particular time. 

Information transferred between processes is referred to as mail. It is sent from one process to 
another through an intermediate storage area called a mailbox. At any given time, a mailbox can 
contain only one item of mail (a message). For any process, there are two sets of mailboxes: 

• The mailbox used for communication between the process and its father. Each process 
has one of these. 

• The set of mailboxes used for communication between the process and its sons. Each 
process has one of these mailboxes for each of its sons. 

Even though there are two sets of mailboxes, between any two processes there is only one mailbox. 

The transfer of mail is based upon a transaction between the sending and receiving processes that 
involves the following steps: 

1- Optionally, the sending process tests the mailbox to determine its status (whether it is 
empty, contains a message, or is being used by the receiving process). 

2. The sending process transmits the mail to the mailbox. The message transferred is a word 
array in the sending process' stack, defined by a starting location and word count. The 
smallest message allowed is a single word. MPE automatically performs a bounds check 
that insures that the array specified actually falls within the limits of the process' stack. 

3. The receiving process optionally tests the mailbox to determine its status. 

4. If the mailbox contains a message, the receiving process collects this mail. If the mail is 
not collected, it is overwritten by additional mail from the sending process. When the 
mail is collected, another bounds check is performed to validate the address given for the 
stack of the receiving process. 

TESTING MAILBOX STATUS 

A process can determine the status of the mailbox used by its father or by a son with the MAIL 
intrinsic. If the mailbox contains mail that is awaiting collection by this process, the length of the 
message, in words, is returned to the calling process. This enables the calling process to initialize 
its stack in preparation for receipt of the message. 
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For example, to test the status of the mailbox associated with one of its son processes, the following 
intrinsic call could be used : 

STATCOUNT:=MAIL(SONPIN,MCOUNT); 

SONPIN contains the Process Identification Number (PIN) of the son process. An integer count 
signifying the length, in words, of the incoming message will be returned to the word MCOUNT. 
The status returned to STATCOUNT will be one of the following values: 

Status Meaning 

The mailbox is empty. 

1 The mailbox contains previous outgoing mail from this calling process 
that has not yet been collected by the destination process. 

2 The mailbox contains incoming mail awaiting collection by this calling 
process. 

3 An error occurred because an invalid PIN was specified or a bounds 
check failed. 

4 The mailbox is temporarily inaccessible because other intrinsics are 
using it in the preparation or analysis of mail. 

SENDING MAIL 

A process sends mail to its father or sons with the SENDMAIL intrinsic. If the mailbox for the 
receiving process contains a message sent previously by the calling process but not collected by the 
receiving process, the action taken depends on the waitfiag parameter specified in SENDMAIL. If 
the mail is being used currently by other intrinsics, the SENDMAIL intrinsic waits until the mailbox 
is free and then sends the mail. 

For example, to send mail to its father, the following intrinsic call could be used: 

STAT:=SENDMAIL(0,3,LOCAT,WAITSTAT); 

The parameters specified are 

pin 0, specifying that the mail is to be sent to the father process. 

count 3, specifying that the length of the message is 3 words. 

locat LOCAT, an array in the stack containing the message to be sent. 

waitfiag WAITSTAT, a logical word. If WAITSTAT = FALSE (bit 15 = 0), 

any mail sent previously will be overwritten. If WAITSTAT = TRUE 
(bit 15 = 1), the intrinsic will wait until the receiving process collects 
the previous mail before sending the current mail. 
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The status returned to STAT is one of the following values: 

Status Meaning 

The mail was transmitted successfully. The mailbox contained no 

previous mail. 

1 The mail was transmitted successfully. The mailbox contained previously- 
sent mail that was overwritten by the new mail, or contained previous 
incoming/outgoing mail that was cleared. 

2 The mail was not transmitted successfully because the mailbox con- 
tained incoming mail to be collected by the sending process (regardless 
of the wait flag parameter setting). 

3 An error occurred because an illegal PIN was specified, or a bounds 

check failed. 

4 An illegal wait request would have produced a deadlock. 

5 The request was rejected because the count specified in the count 

parameter exceeded the mailbox size allowed by the system. 

6 The request was rejected because storage resources for the mail data 

segment were not available. 

RECEIVING (COLLECTING) MAIL 

A process collects mail transmitted from its father or a son with the RECEIVEMAIL intrinsic. 
If the mailbox for the receiving process is empty, the action taken depends on the waitflag pa- 
rameter specified in RECEIVEMAIL. If the mailbox is being used currently by other intrinsics, the 
RECEIVEMAIL intrinsic waits until the mailbox is free before accessing it. 

To collect a message from a son process, the following intrinsic call could be used: 

STAT:=RECEIVEMAIL(SONPIN,MDATA, WAITSTAT); 

The parameters specified are 

P in SONPIN, which contains the Process Identification Number of the son 

process. (Zero for father process.) 

location MDATA, an array in the stack in which the incoming mail will be 

stored. 

waitflag WAITSTAT, a logical word. If WAITSTAT = TRUE (bit 15 = 1), the 

intrinsic will wait until the incoming mail is ready for collection. If 
WAITSTAT = FALSE (bit 15 = 0), the intrinsic will return to the 
calling process immediately. 
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One of the following status codes is returned to STAT: 

Status Meaning 

The mailbox was empty (and WAITSTAT was FALSE). 



1 



No message was collected because the mailbox contained outgoing 
mail from the receiving process. 



2 The message was collected successfully. 

3 An error occurred because of an illegal PIN or a bounds check failed. 

4 The request was rejected because waitflag specified that the receiving 

process should wait for mail if the mailbox is empty, but the other 
process sharing the mailbox is already suspended, waiting for mail. If 
both processes were suspended, neither could activate the other, and 
they may be deadlocked. 

AVOIDING DEADLOCKS 

Since the simultaneous use of mail transmission, process suspension, and RIN locking intrinsics 
throughout a process structure could result in a deadlock if the intrinsic calls are not synchronized 
properly, you should be aware of the following: 

1. In a multi-process job/session, whenever a process is suspended (through the SUSPEND 
intrinsic, or when locking a RIN or receiving mail), MPE does not determine whether 
all other processes in the tree are suspended. You must exercise caution in avoiding such 
a situation. 

2. An attempt by a process to lock a global RIN succeeds only if two conditions are met: 

a. No other process within the job/session currently has locked this RIN — a 
global RIN cannot be used as a local RIN, because deadlock within the same 
job/session could otherwise occur. 

b. The calling process currently has no other global RIN locked for itself. This 
could otherwise result in deadlock between two jobs/sessions. 

Dccrupniu iwrs PROCESSES 

When a process is created, it is scheduled on the basis of a priority class assigned by its father. After 
this point, its priority class can be changed at any time with the GETPRIORITY intrinsic. A process 
can change its own priority or that of a son but it cannot reschedule its father. 

Generally, MPE schedules processes in linear or circular subqueues, as described in the MPE General 
Information Manual. The standard linear subqueues are 

• The AS subqueue, containing processes of very high priority. 

• The BS subqueue, containing processes of high priority. 
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The circular subqueues are 

• The CS subqueue recommended for interactive processes. 

• The DS subqueue, available for general use at a lower priority than the CS subqueue and 
recommended for jobs. 

The subqueue to which a process belongs determines the priority class of the process. From highest 
to lowest priority, these classes (named after their subqueues), are 

AS 
BS 
CS 
DS 
ES 

To reschedule itself with the priority class "D", a process would make the following call: 
GETPRIORITY (0,"DS"); 

The parameter specifies that the calling process is rescheduling itself. If the process were re- 
scheduling a son process, the Process Identification Number of the son processes would be 
specified. 

DETERMINING SOURCE OF ACTIVATION 

After a suspended process is reactivated, it can determine whether the source of the activation 
request was its father process or one of its son processes with the GETORIGIN intrinsic call. 

For example, the following intrinsic call could be used: 

SOURCE:=GETORIGIN; 
One of the following codes would be returned to SOURCE: 

1 Activated by its father. 

2 Activated by a son. 

DETERMINING FATHER PROCESS 

A process can determine the Process Identification Number of its father with the FATHER 
intrinsic. 

For example, the following intrinsic call could be used : 

PIN:=FATHER; 
The Process Identification Number of the father is returned to PIN. 



7-14 



DETERMINING SON PROCESSES 

A process can request the return of the Process Identification Number assigned to any of its sons 
with the GETPROCID intrinsic. 

For example, the following intrinsic call would return the Process Identification Number of the 
sixth existing son of the calling process to the word PINNUM: 

PINNUM:=GETPROCID(6); 

DETERMINING PROCESS PRIORITY AND STATE 

A process can request the return of a double-word message denoting the following information 
about its father or sons with the GETPROCINFO intrinsic: 

Word Bits Meaning 

1 (8:8) The process' priority number in the master queue. 

(0:8) Reserved for MPE. These bits are set to zero by the system. 

2 (15:1) Activity State. 

1 = The process is active. 

= The process is suspended. 

(13:2) Suspension Condition. (Set only if bit 15 = 0) 

01 = The process expects to be activated by its father. 
10 = The process expects to be activated by a son. 

(9:4) Reserved for MPE. These bits are set to zero by the system. 

(7:2) Origin of the last ACTIVATE Call. 

01 = Father. 

10 = Son. 

00 = MPE. 

(4:3) Queue Characteristics. 

001 = DS or ES priority class. 
010 = CS priority class. 

100 = Linearly scheduled (AS or BS Master queue). 
(0:4) Reserved for MPE. These bits are set to zero by the system. 

For example, to request information about its father, the following intrinsic call could be used: 
INFO:=GETPROCINFO(0); 

The parameter specifies that the process is the father. If the process were a son process, the 
Process Identification Number of the son process would have been specified. 
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The information returned to the double- word INFO is of the following form: 











Not Used 












Priority 








Bits 





1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 


Wordl: 



































1 


1 


1 


1 





Word 2: 














1 











1 














1 









Not Used 



Queue 



Not Used 



ACTIVATE 
Origin 

The information is interpreted as follows for the father process: 

Word Bits Value 



* Activity 

State 



Suspension 
Conditions 



Meaning 



(8:8) 


%36 


(0:8) 





(15:1) 





(14:1) 





(13:1) 


1 


(9:4) 





(7:2) 


1 


(4:3) 


4 



Process has priority 30 in master queue. 
Not used. 



Process is suspended. 

u 1 

| Process to be activated by its son. 

Not used. 

Origin of last ACTIVATE call was father of this process. 

Circular subqueue. 
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MANAGEMENT CAPABILITY 



SECTION 



VIII 



During execution of a user program, many processes may be created, run, and deleted. For each 
process in execution, one or more code segments, and one data segment, exist. The data segment is 
private to the process and contains the data generated and manipulated by that process. In a user 
process, this segment is referred to as the user's stack segment. 

NOTE 

See the MPE General Information Manual for discussions of 
segments, processes, and the stack. 

A particular program, which consists of code segments, can be run by many user processes 
simultaneously, with all user processes accessing the same body of code. The stack segment, however, 
is private to each user process and cannot be shared among others. Additionally, user processes 
created by a user with the standard MPE capabilities may create and access one stack segment only. 

MPE allows users with the Data Segment Management Capability, however, to create and access 
extra data segments for their processes during a job or a session. These segments are used for 
temporary storage of data while the creating processes exist. Each segment is assigned an identity 
that either allows it to be shared between different processes in a job or session, or declares it 
private to the creating process. When a process terminates, all private data segments created by it 
are destroyed automatically. Sharable data segments are saved until explicitly deleted or until the 
job or session ends, at which time they are destroyed. 

Extra data segments are not directly addressable by user processes. They can be accessed only 
through intrinsics that move data between the user's stack and the extra data segments (DMOVIN, 
DMOVOUT). If a process not having the Data Segment Management Capability attempts to call 
these intrinsics, that process is aborted. The Data Segment Management Capability is assigned to 
the process at :PREP time by a user with this capability (:PREP . . . ; CAP = DS). 

The maximum number of extra data segments allowed per process is determined at system 
configuration time, and this number may not be exceeded. 

tv „ ,,„™. ,„u^ nAc^ccic <-Vio Dnfn Sea-merit Management Caaability. you can 

• Create an extra data segment. 

• Transfer data from an extra data segment to the stack. 

• Transfer data from the stack to an extra data segment. 

©pvionffo +v.p owo r>f a" pvt.ra data segment. 

• Delete an extra data segment. 
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CREATING AN EXTRA DATA SEGMENT 

A process can create or acquire an extra data segment with the GETDSEG intrinsic. The number 
of extra data segments that can be requested, and the maximum size allowed these segments are 
limited by parameters specified when the system is configured. When an extra data segment is 
created, the GETDSEG intrinsic returns to the calling process a logical index number, assigned by 
MPE, that allows this process to reference the segment in later intrinsic calls. The GETDSEG 
intrinsic also is used to assign the segment an identity that either allows other processes in the same 
job or session to share the segment, or that declares it private to the calling process. If the segment 
is sharable, other processes in the same job/session can obtain its logical index (through GETDSEG) 
and use this index to reference the segment. Thus, the logical index is a local name that identifies 
the segment throughout any process that obtained the index with the GETDSEG intrinsic call 
The logical index need not be the same value in all processes sharing the same data segment The 
GETDSEG intrinsic may return different logical index numbers to different processes, even though 
each process referenced the same data segment in their intrinsic calls. The identity, on the other 
hand, is a job-wide or session-wide name that allows any process to identify the data segment in 
order to obtain a logical index for it. 

Figures 8-1, 8-2, and 8-3 contain three programs which illustrate the use of the GETDSEG 
DMOVOUT, and DMOVIN intrinsics. 

Together, the three programs perform the following: 

1. Create an extra data segment which can be shared by all three processes. 

2. Compute Julian calendar dates for any year and store these dates in an array. 

3. Transfer the Julian calendar dates from the array to the extra data segment. 

4. Create and activate two processes of the program shown in figure 8-3, each of which 
shares the same code but has its own data stack. 

5. Each of the processes created in 4 above: 

a. Opens a terminal for input/output and, once a :DATA filename command is 
entered on the terminal, requests month and day information from the user. 

b. Moves the Julian dates, for the month entered by the user, from the extra 
data segment to its own stack. 

c Computes the Julian date based on the day of the month entered by the user 
and displays this information on the terminal. 

The program in figure 8-1, called DSINIT, creates an extra data segment 372 words long fills an 
array with values representing Julian calendar dates for a particular year entered by a user, then 
transfers this information from its stack to the extra data segment. 

The program in figure 8-2 called DSBOSS, creates and activates two processes. Each of the two 
processes created is a process to run the program shown in figure 8-3, thus each process shares 
the same code but has its own data stack. 
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SC0NTRUL USLINI1 
BEGIN 

BYTE ARRAY INPUT C : 5 ) : = " 1 NPUT "; 

BYTE ARRAY OUTPUT CO : 6 ): ="OUTPUT "; 

INTEGER IN,UUT,LGTH, MONTH. DAY, YEAR, DATE:=1 , DSLGTH: =372; 

LOGICAL DSINDX; „_ „ _. 

ARRAY HEADC0:14):="GENERATE CALENDAR DATA SEGMENT" J 

ARRAY bUFRCO: 1):=2(" ") f 
BYTE ARRAY bBUF'(*)=BUKR; 
ARRAY RKGlSTC0:5): = n £NTER YEAR: "; 
INTEGER ARRAY MAXDAY CO : 1 1 J : = 31 , 28 , 31 # 30 , 3 1 , 30 , 

31,31,30,31,30,31; 

INTEGER ARRAY C ALENDARC : 371 ) : =372 (-1) ; 
DEFINE CCL = IE < THEN OUIT#, 
CCME= IF <> THEN U I T # ; 

INTRINSIC FOPEN,FREAD,FWRITE,GETDSEG,DMOVOUT, BINARY, QUIT; 
<<END OF DECLARATIONS>> 



IN:=F0PEN(INPUT,%45); CCLC1); 

OUT: sFOPKNC OUTPUT, %414, 1) : CCLC2) ; 

K WRITE COUT, HEAD, 15,0); CCNEC3); 

'GgTDSECtDSItfDX^DSLCTH^JP"): CCLC4) 

F^.R1TE(OUT,REUST,6,%320); CCNEC5); 
LGTH:=FREADCIN,BUFR,-4); CCNEC6); 
YEAR:=BINARYCBBUF,LGTH); CCNEC7): 



<<SSTDIN» 
<<SSTDLIST>> 

<<PROGRAM ID» 

l<SHARED EXTRA D5» - 

<<REOUEST CALENDAR YEAR>> 
«INPUT YEAR» 
«CONVERT YEAR>> 



IF YEAR HUD 4 = THEN MAXDAYC 1 ) : = 29 ; «FIX FEB FOR LEAP YEAR» 

Pim yoNTH-=0 UNTIL 11 DO «INDEX 12 MONTHS» 

FOR DAY: =0 UNTIL MAXDAYCMONTH)-! DO «1NDEX DAYS IN EA MONTH» 

BEGIN 

CALENDAPCMONTH*31+DAY):=DATE; 

DATE:=DATE+l; 

END; 



«SET IN JULIAN DATE>> 
«INCR JULIAN DATE» 



END. 
K = % 9 1 



NO. ERRURS=000; 
PROCESSOR TIKE=0:00:03; 



0«O«OUT{DSi*DX,0, 3?2, CALENDAR) J 

CCNEC8); 

SECUNDARY DB STORAGE=%006 36 
NO. WARhINGS=000 
ELAPSED T1MF=0:00:10 



<< JULIAN CALENDAR TO DS» 
"«CHECK FOR ERROR>> 



Figure 8-1. Using the GETDSEG and DMOVOUT Intrinsics (Program DSINIT) 
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SCONTKOL USLINIT 
BEGIN 

BYTE ARRAY INPUTCO :5 ):=" INPUT " ; 

BYTE ARRAY OUTPUT ( : 6 ) :="OUTPUT " • 

INTEGER IN,0UT,LGTH,P1N1,RIN2; 

BYTE ARRAY PFILECO :6) :=»DSACCS "• 

ARRAY MES5AGE(0:29)S="WHEN ALL JULIAN DATE OPERATIONS ARE «, 

-COMPLETE TYPE: DONE. " ,%6412, "? "; 

ARRAY BUFR(0:l); ' ! ' 

BYTE ARRAY BBUFC*)=BUFR; 

DEFINE CCL= IF < THEN QUIT*, 

CCNEs IF <> THEN QUITO; 

INTRINSIC FOPEN,FWRITE,FREAD, CREATE, ACTIVATE, QUIT; 
<<END OF DECLARATIONS» 



00036 
00012 
00025 1 
00025 1 
00037 1 
00051 1 
00051 1 
00060 1 
00067 1 
00067 1 
00067 1 
00077 1 
00110 1 
00110 1 
00131 1 
PRIMARY DB STORAGE 
NO. ERRORS=000; 
PROCESSOR TIME=0:00 



IN:=F0PEN(INPUT,%45); CCLCl); 
OUT: =F0PEN (OUTPUT, %41 4,1); CCLC2); 

Oh A'l ".( P* II. K, . PIN 1 , « | * ) j Cl Nf.{ i I ; 
C-HEAlr(fMLl,,P|N;,- 2"); CCMU4J? 

AC' r I * ATE I H 1 SI . ; f CCNfc ( } > ; 

*C r i V A IE C K,,U2 r & J } CCHL ( o ) ; 



wait: 



END. 
%013; 

:02; 



FWR1TECUUT, MESSAGE, 30, %320); CCNFC7) 
LGTH:=FREAD(IN,BUFR,-4); CCNEC8); 

IF BBUFO-DONE" THEN GO WAIT; 

SECONDARY DB STORAGE=%00053 
NO. WARNINGS=000 
ELAPSED TIME=0:00:09 



<<SSTDIN» 
<<SSTDLIST>> 

<*suh t uses -Tf.mim rtL2>* ■ 

<Xtitl* i l,i»f.6 rERMI02 Tlhh» 

«5DN 1» 



«TERMINATION INSTRUCTIONS>> 

«SUSPEND FOR READ» 

<<IF DONE - END KILLS SONS» 



Figure 8-2. Creating and Activating Two Son Processes (Program DSBOSS) 
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00051000 

00OS2O00 

00053000 

PPIMARY 

NO. ERRO 

PROCESSO 



00000 
00000 
00000 1 
00005 1 
00004 1 
00004 1 
00004 1 
00012 1 
00012 1 
00012 1 
00021 1 
00021 
00021 
00021 
00021 
00021 
00021 
00021 
00021 
00003 



1 
1 
1 
1 
1 
1 
1 
1 
1 

00015 1 
1 
1 
1 
1 
1 
1 



00020 
00020 
00030 
00034 
00037 
00037 

00047 1 

00061 1 

00072 1 

00075 1 

00102 1 

00 103 1 
00112 1 
00112 1 
00123 1 
00132 1 
00143 1 

00150 1 

00151 1 
00156 1 
OOlol 1 
00161 2 
00166 2 



UU1M 



SCflWTROL U5LIN1T 
BEGIN 

BYTE ARRAY NAME C : 7 ) : =" TERMIO# ": 

BYTE ARRAY DEV ( : 4) : ="TERM "; 

INTEGER FNO, LGTH, MONTH, DAY, DSLGTH, JDATE, CURRENT: =-1 ; 

LOGICAL L>SINDX,PARM = Q-4; 

ARRAY HEADC0:9): = "JULIAi<l DATE CALENDAR"; 

ARRAY BUt R(0:1); 

BYTE ARRAY BBUFR C*)=BUFR; 

ARRAY MESSAGECOllb) :="MONTH 

BYTE ARRAY BMSG ( * ) =MESSAGE ; 

ARRAY DATESC0:3Q); 

DEFINE CCNE = IF <> THEN QUITS; 



","DAY = ", "JULIAN DATE 



INTRINSIC F0PEU,FREAD,F*R1TE,GETDSEG,DM0V IN, BINARY, ASCI I, QUIT; 



<<EfcD OF DECl.ARATIONS>> 

NAMEC6) J=PABM; 
FNO:=FOPEnCNAME,%405,4,36,DEV) ; 

IF < THEN QUITC1); 

F W R I T E ( F NO, HEAD, 10,0); 
GETD5EGCI>5t«PX»DSLCTH/"JD")J 
IF <= THEN QUlT(3); 
GETMO: 



GETDA: 



FARITECFNO,MESSAGE,4,%320); CCNEC4); 

HOVE BUFR:=" "; 

LGTH:=FREADCFNO,BUFR,-2); CCNEC5); 

IF LGTH=0 THEN GO EXIT; 

MONTH :=B1NARY(BHUFR, LGTH); 

IF <> THEN GO GETMO; 

IF NOr(l<=MONTH<=12) THEN GO GETMO; 

Fir,RIT£(FNO,MESSAGEC4),3,%320); CCNE(6 

MOVE BUFR:=" ": 

LGTH:=FREAD(FN0,BUFP,-2); CCNEC7); 

DAY:=BINARY(BBUFR,LGTH) ; 

IF <> THEN GO GETDA; 

IF NOTCK = DAY<=31) THEN GO GETDA; 

IF MOMTHOCUPRENT THEN 

, main " ■ 

r:-Ovi:;C"."iMLiX, ■•«■ nti-.-i)«31 ,31 * 

DATES}} CC#£<8); 

, itL ur -iT « ™^'j* th * 

00175 2 ' Ml^iiP™SMiMiili'i»PiPiiwis»«wiii 

00175 1 jbATE:=DATES(DAY-l); 

00201 1 IF JDATE<0 THEN GO GETDA; 

00204 1 MOVE MESSAGEC143:=" "! 

00216 1 LGTH:=ASCIICJDATE,10,BMSG(28)): 

00 225 1 FWRTTE(FNO,MESSAGE(7),10,0); CCNE19); 

00236 1 GO GETMO: 

00237 1 EXIT:END. 

DB STORAGE=%020: SECONDARY DB STORAGE=%00103 

RS=000; 1^0. *APNINGS=000 

R TIME=0:00:03; ELAPSED TIME=0:00:13 



<<SET FORMALDES #=1 OR 2» 
«TERMINAL FILE TERMIO* » 
«CHECK FOR ERROR>> 

<<PR0GRAM ID>> 
«SHARE0 CALENDAR DS» 
**<ERP,OR OR NONEXlSfENT>> 

<<REQUEST M0NTH» 
«BLANK READ BUFFER>> 
«INPUT MONTH» 
<<NO MONTH - DONE» 
<<C0NVERT M0NTH» 
<<1F BAD TRY AGAIN» 
<<1LLEGAL MONTH CHECK>> 

);«REQUEST DAY>> 

<<BLANK READ BUFFER» 
<<1NPUT DAY» 
«CONVERT DAY» 
«IF BAD TRY AGAIN» 
<<ILLEGAL DAY CHECK>> 
<<MONTH NOT IN BUFFER>> 

f.OET WJNT8 FRO* ZZM'm*&P» 
«CH£CK FOR S,mW» 
«UPDAiE *ON?» W fcUFFt?» 

<<Gfl JULIAN S-ATE>> 
«UNINIT1ALIZED DATE» 
«BLANK OUTPUT BUFFER>> 
<<CONVERT JULIAN DATE» 
<<OUTPuT DATE ON ic^nxv^w *-r 
«CONTINUE» 



Figure 8-3. Using the GETDSEG and DMOVIN Intrinsics (Program DSACCS) 
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The program in figure 8-3, called DSACCS, opens a terminal for input/output, acquires the extra 
data segment created by DSINIT, requests a month and day from the user, then transfers the Julian 
dates contained in that particular month into its own data stack. Because DSBOSS (figure 8-2) has 
created two processes for the program shown in figure 8-3, and has activated both processes the 
functions performed by DSACCS are duplicated (i.e., two terminals are opened for input/output, 
two users can enter the month and day, etc.). 

NOTE 

The three programs in figures 8-1, 8-2, and 8-3 must specify 
the Data Segment and Process Handling capability when they 
are prepared, as follows: 

DSINIT (figure 8-1) 

:PREP $OLDPASS,DSINIT;CAP=DS 

DSBOSS (figure 8-2) 

:PREP $OLDPASS,DSBOSS;CAP=PH 

DSACCS (figure 8-3) 

:PREP $OLDPASS,DSACCS;CAP=DS 

In all cases above, it is assumed that $OLDPASS contains 
the compiled USL file for each of the three programs. 

In figure 8-1, the statement 

INTEGER ARRAY MAXDAY(0:11):=31,28,31,30,31,30, 

31,31,30,31,30,31; 

initializes a 12-word integer array to represent the number of days in each month of the year. 
The statement 

INTEGER ARRAY CALENDAR(0:371):=372(-1); 
declares a 372-word integer array and initializes all 372 words to -1. 

The two FOPEN intrinsic calls open $STDIN and $STDLIST so that FREAD and FWRITE intrinsic 
calls can be issued against these files. 

An extra data segment is created with the statement 

GETDSEG(DSINDX,DSLGTH," JD") ; 

The parameters specified are 

mdeX The lQ g ical wor d DSINDX, to which the logical index number of the 

data segment will be returned. This index is used to refer to this data 
segment in later intrinsic calls from this process. 
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length DSLGTH, which has been initialized to 372 words (see statement 

number 5 in figure 8-1). 

id "JD", which specifies that this data segment is sharable by other 

processes in the same job/session. Note that any process which is to 
create or share an extra data segment must have the Data Segment 
Capability. If the data segment being created were to be private to the 
creating process, zero would be specified for id. 

Statements 28, 29, and 30 in figure 8-1 request the user to enter the calendar year, and convert 
this ASCII string to a binary value. 

The statement 

IF YEAR MOD 4 = THEN MAXDAY(1):=29; 

checks if the year is equally divisible by 4 and, if it is, adds the 29th day to February for the leap 
year. 

The six statements beginning with 

FOH MONTti:=u uNii-L, ukj 

establish two FOR loops. The inner loop steps from to the maximum number of days minus 1 for 
each entry in the array MAXDAY. For example, when MONTH = 0, MAXDAY(MONTH) = 31, 
thus the FOR loop performs 31 iterations (0 to MAXDAY(MONTH) -1). 

The statement 

DATE:=DATE+1; 

increments the date each time the FOR loop is repeated. When the inner loop is satisfied, the 
MONTH FOR loop steps one iteration and the inner loop repeats. The array CALENDAR thus is 
filled with Julian dates as shown in figure 8-4. The array is linear, of course, and is shown as a 
day/month matrix for illustrative purposes only. All elements of the array were initialized to -1, 
and positions in the array that retain the value -1 signify invalid dates. 

The data contained in CALENDAR is transferred from the stack to the extra data segment with 
the statement 

DMOVOUT(DSINDX,0,372,CALENDAR); 

The parameters specified are 

index DSINDX, which contains the logical index returned by MPE when the 

GETDSEG intrinsic was executed. 

disp 0, specifying the first word in the data segment. This is the starting 

location for the first word transferred from CALENDAR to the extra 
data segment. 
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Figure 8-4. Array CALENDAR 



number 
location 



372, specifying the size, in words, of the data block to be transferred. 
CALENDAR, the data block to be transferred begins at the address in 



the stack specified in CALENDAR. 
At this point, the following events have occurred: 









CALEND/ 
1976 ENT 


^R YEAR 


:RUN UbiiMi i 




ERED 








< 


1 






ARRAY CALENDAR 
FILLED WITH 
JULIAN DATES 




r 




i 


< 


EXTRA DATA 




DATA IN CALENDAR 
TRANSFERRED TO 


SEGMF 
CREA1 


fED 




EXTRA DATA SEGMENT 



When the :RUN DSBOSS command is entered, the program in figure 8-2 (DSBOSS) executes. 
Statements 18 and 19 open $STDIN and $STDLIST to accept FREAD and FWRITE intrinsic calls. 
The statement 

CRE ATE(PFILE„PIN1 ,"1 ") ; 
creates a process. The parameters specified are 

progname PFILE, a byte array containing the string "DSACCS" which j the 

name of the file containing the program to be run. Note that DSALCb 
is the name of the program in figure 8-3, thus the process is created for 
this program. 



entryname 
pin 

param 



Omitted. The primary entry point is specified by default. 

PIN1, a word to which the Process Identification Number of the 
process will be returned. 

"1", a parameter used to transfer control information to the new 
process. The new process can access this control information ("1") in 
location Q - 4 of its data stack. 



All other parameters are omitted from the CREATE intrinsic call. 

The statement 

CREATE(PFILE„PIN2,"2"); 

also creates a process for the program DSACCS. This time the Process Identification Number is 
returned to PIN2, and the control parameter "2" is located at stack location Q - 4 for this process. 

8-9 



The two ACTIVATE intrinsic calls activate the two processes. Note that the susp parameter 
specifies that the father process will not be suspended when the sons are activated. Program DSBOSS 
therefore, has created and activated two processes as follows: 




The four statements beginning with 
WAIT: 



suspend DSBOSS for I/O until "DONE" is entered on $STDIN. DSBOSS did not suspend when 
the sons were activated. The reason for this is that when two or more sons are created and the 
father is suspended when the last son is activated, it is possible that the sequence of events will be 
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such that the sons are unable to reactivate the father. The following sequence illustrates how this 
could happen: 

1. Create two sons. Activate SON1. 
Father and SON1 both active. 

2. Activate SON2. Suspend father. Father expects to be reactivated when either son 
terminates. 

Father suspended; SON1 and SON2 active. 

3. SON1 terminates, reactivating father. Father reactivates, determines that SON2 is still 
active, and re-suspends itself. However, while father was active, SON2 terminated. 
Attempt to reactivate father failed because father already was active. Thus, when father 
re-suspends itself, it suspends indefinitely because both sons have terminated. 

The two processes, SON1 and SON2, both of which are DSACCS, are shown in figure 8-3. 
The statement 

opens a terminal for input/output. The parameters specified are 

formaldesignator NAME, which contains the string TERMI01 when this call is issued by 

SON1 and TERMI02 when the call is issued by SON2. Note that in 
statement number 3 ; NAME is set equal to TERMIO#. The statement 

NAME(6):=PARM; 

however, replaces ff with 1 or 2, depending on the parameter contained 
in stack location Q - 4 (this parameter was passed to the process by 
the CREATE intrinsic call in program DSBOSS). Thus, by using 
different formal designators, SON1 opens one terminal and SON2 opens 
another. 

NOTE 

Unlike disc files, where each formal designator must be 
unique in its domain (temporary or permanent), two or 
more devices can be opened with the same formal designator. 
For example, two :DATA commands 

:DATA FIELD.SUPPORT;TERMIO 
:DATA FIELD.SUPPORT;TERMIO 

would cause MPE to search the device directory for two 
available terminals and, if two are available, both would be 
allocated. Using different formal designators, however, allows 
a user to direct output to a particular terminal with a :FILE 
command. 
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foptions %405, which specifies the following: 

a. Old file. 

b. ASCII. 

c. Actual file designator is the same as the formal file designator. 

d. Fixed-length records. 

e. Carriage-control character expected. 
aoptions 4, which specifies input/output access. 
recsize 36, specifying 36 words. 

device DEV, a byte array specifying the device class ("TERM"). 

AH other parameters are omitted from the FOPEN intrinsic call. 

The shared data segment is acquired with the statement 

GETDSEG(DSINDX,DSLGTH,"JD"); 

Note that the process quits unless the CCG condition code, signifying that an extra data segment 
with this identity exists already, is returned (see statement number 25). 

A month is requested from the user and the input is converted to binary. The user then is requested 
to enter a day and this information is read and converted to binary. 

The statement 

IF MONTH < > CURRENT THEN 

checks whether the month information is different than the information currently in the stack. 
If it is, the statement 

DMOVIN(DSINDX,(MONTH-l ) * 31 ,31,DATES) ; 

transfers the Julian dates for the month entered by the user into the 31-word array DATES For 
example, if the user entered 3, the values 61 through 91 (see figure 8-4), corresponding to the 
Julian calendar dates for the month of March are transferred from the extra data segment to the 
array DATES in the stack. Data representing the entire month, instead of data representing the 
specific day entered by the user, is transferred by DMOVIN because DMOVIN, which requires 
considerable time to execute, should be used sparingly to maintain programming efficiency. Trans- 
ferring the data for the entire month saves time if the user's next request is for a Julian date in the 
same month. Note that months are numbered from to 11. 
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The buffer CURRENT is updated to the current month with the statement 

CURRENT :=MONTH; 
The Julian date is computed with the statement 

JD ATE :=DATES(DAY-1 ) ; 
and this information is output to the user. 
The three examples below illustrate using the three programs shown in figures 8-1, 8-2, and 8-3. 

EXAMPLE 1 

: RUN PS I NIT 

GENERATE CALENDAR DATA SEGMENT 
ENTER YEAR: 1976 

END OF PROGRAM 
I RUN DSB0S5 

WHEN ALL JULIAN DATE OPERATIONS ARE COMPLETE TY*E: DONE. 
? DONE 

END OF PROGRAM 

EXAMPLE 2 

: DATA FI ELD * SUPPORT; TERMI 01 

JULIAN DATE CALENDAR 

MONTH = _H 

DAY = 31 

DAY = 30 

JULIAN DATE = 335 

MONTH = 2 

DAY = 2j5 

JULIAN DATE = 60 

MONTH = 6 

DAY = 1# 

DAY = j_3 

JULIAN DATE = 1 65 

MONTH = 1_3 

MONTH = Z 

MONTH = 3 

DAY = 29 

JULIAN DATE = 89 

MONTH = 
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EXAMPLE 3 

i DATA FIELD. SUPPORT J TERM 102 

JULIAN DATE CALENDAR 

MONTH = ^9 

MONTH = 9. 

DAY = 1 5 

JULIAN DATE = 259 

MONTH = 7_ 

DAY = j20 

JULIAN DATE =202 

MONTH = _8 

DAY = J_4 

JULIAN DATE = 227 

MONTH = 5 

DAY = 3 



In example 1, the command :RUN DSINIT causes DSINIT to execute. It prints the purpose of the 
program and a request to the user to enter the year for which Julian dates are required. When 1976 
is entered, DSINIT creates an extra data segment, fills an array with Julian dates for the year 1976 
transfers this data to the extra data segment, and terminates. 



The :RUN DSBOSS command causes DSBOSS to execute. DSBOSS creates and activates two 
processes (DSACCS), then suspends itself after the message 

WHEN ALL JULIAN DATE OPERATIONS ARE COMPLETE TYPE- DONE 
? 

Example 2 illustrates the SON1 process execution. 



son 



1. 



A user enters a :DATA statement on a terminal. (Remember that SON1 and SON2 have 
each opened a terminal for input/output.) 



2. MPE searches the device class directory for a terminal with the formal designator 
TERMI01, and allocates the terminal. 

In response to the month and day requests, the user enters 

MONTH = 11 

DAY = 31 
DSACCS determines that 31 is not a valid day for month 11 with the statement 

IF JDATE < THEN GO GETDA; 

(see figure 8-3). Recall that invalid dates in the array CALENDAR (see figure 8-4) are signified 
by -1. DSACCS prompts for a new day and the user enters 30. DSACCS computes the Julian 
date for November 30th and displays: 

JULAIN DATE = 335 

Example 3 shows a second user accessing terminal 2. 
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When a user types DONE on $STDIN, see example 1, the father process terminates, terminating 
both sons. 

DELETING AN EXTRA DATA SEGMENT 

A process can release an extra data segment assigned to it with the FREEDSEG intrinsic. If this is a 
private data segment, or if it is a sharable segment not currently assigned to any other process in the 
job/session, the segment is deleted from the entire job/session. Otherwise, it is deleted from the call- 
ing process but continues to exist in the job/session. 

For example, to delete a data segment with the logical index contained in INDX, the following 
intrinsic call could be used. Because the id parameter is specified as 0, the data segment is deleted 
from both the process and the job. 

FREEDSEG(INDX,0) ; 

TRANSFERRING DATA FROM AN EXTRA DATA SEGMENT TO 
THE STACK 

A process can copy a block of words from an extra data segment into the stack with the "MO , *N 
intrinsic. A bounds check is performed by the intrinsic on both the extra data segment and the 
stack to insure that the data is taken from within the data segment boundaries and moved to an area 
within the stack boundaries. 

The DMOVIN intrinsic call is illustrated in Figure 8-3 and described on page 8-12. 

TRANSFERRING DATA FROM THE STACK TO AN EXTRA 
DATA SEGMENT 

A process can copy a block of words from the stack to an extra data segment with the DMOVOUT 
intrinsic. A bounds check is performed by the intrinsic to insure that the data is taken from an area 
within the stack boundaries and moved to an area within the extra data segment. 

The DMOVOUT intrinsic call is illustrated in Figure 8-1 and described on page 8-7. 

CHANGING THE SIZE OF AN EXTRA DATA SEGMENT 

You can change tne current size oi an extra aaia segment, wiui me iu.iu^u """"° ,v " ™ " u j^" 
application, disc storage for a new segment is obtained by calling the GETDSEG intrinsic. Sufficient 
virtual space is allocated by the system to accommodate the original length of the data segment. 
This virtual space usually is allocated in increments of 512 words (depending on how the system is 
configured). For example, creation of a data segment with a length of 600 words would result in 
two increments of 512 words being allocated for the data segment space, thus resulting in 1024 
words. 

_ „» j • i j.u~ a t Tnopd ir.tmr.ctls> +.-. yarlii^o tVio cfnrsjcrp rpnnirpd hv 

Unce disc storage is ODtameu, yuu van use mc n.i^j.u^>^yj ^w"" 1 - >~ *<-«-~~ »•- — -- » 1 — -- ~* 

the segment when it is moved into main memory, then later expand it as needed for more efficient 

use of memory. In no case, however, can ALTDSEG be used to increase segment size beyond the 

virtual space originally allocated through GETDSEG. 
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The form of the ALTDSEG intrinsic call is 

ALTDSEG(INDEX,INC,SIZE) ; 
where 

INDEX is a word containing the logical index of the extra data segment, obtained through the 
GETDSEG intrinsic call. 

INC is the value, in words, by which the extra data segment is to be changed. A positive integer 
value specifies an increase and a negative integer value specifies a decrease. 

SIZE is a word to which is returned the new size of the data segment after incrementing or 
decrementing has occurred. 



8-16 



PRIVILEGED MODE CAPABILITY 



SECTION 



IX 



If you are an MPE user with standard MPE capabilities, you can access only your own code and data 
areas in main memory. But if you are a user with the Privileged Mode Capability, you can access all 
areas of the system and can use all features of the hardware. You can access all system tables, and 
can invoke all system instructions, including those in the privileged central processor instruction set. 
You can, in short, use the computer on the same terms as MPE itself. (In fact, MPE does not 
distinguish a privileged user as not being MPE itself.) 

IMPORTANT NOTE 

The normal checks and limitations that apply to the standard 
users in MPE are bypassed in privileged mode. It is possible 
for a privileged mode program to destroy file integrity, includ- 
ing the MPE operating system software itself. Hewlett-Packard 
will investigate and attempt to resolve problems resulting 
from the use of privileged mode code. This service, which is 
not provided under the standard Service Contract, is available 
on a time and materials billing basis. However, Hewlett-Pack- 
ard will not support, correct, or attend to any modification 
of the MPE operating system software. 



You can use the Privileged Mode Capability in two ways: 

1. You can write permanently privileged programs that are loaded and executed entirely in 
privileged mode. 

2. You can write temporarily privileged programs that dynamically enter and leave 
privileged mode during execution, as required. 

dcduamcmti V PRIVII FfiFD PROGRAMS 

i- |m| 1IVI J-ll YtalV ■ fc ■ ■ ■■■w . — —— — — - - - ■ 

A program's segments are loaded and executed directly in privileged mode when all three of the 
following conditions exist: 

1. Any of the program's code segments contain privileged instructions. ($OPTION 
PRIVILEGED is used.) 

2. The program is prepared with the Privileged Mode Capability, by entering the appropriate 
capability-class attribute in the caplist parameter of the :PREP or :PREPRUN command 
that prepares the program. (See the MPE Commands Reference Manual for discussions of 
the :PREP and :PREPRUN commands.) Note that entering a privileged capability class 
attribute requires that you have been assigned the Privileged Mode Capability. 
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3. The NOPRIV optional parameter is omitted from the :PREPRUN or :RUN command 
that executes the program, or the CREATE intrinsic that creates a process to run it. This 
omission leaves the privileged mode bit in the appropriate CST entries on. 

When you add a segment to a Segmented Library (through the -ADDSL Segmenter command), the 
procedures within the segment are checked to determine if any one of them is privileged. If it is, the 
segment is always run in privileged mode. In order to add a segment containing one or more 
privileged procedures to a library, you must possess the Privileged Mode Capability. See the MPE 
Segmenter Reference Manual for instructions concerning Segmented Libraries. 

TEMPORARILY PRIVILEGED PROGRAMS 

Temporarily privileged programs are initiated, upon request, in the non-privileged mode. Then, 
intrinsics can be used to change the program to and from the privileged mode dynamically. For 
example, just before a set of privileged instructions is encountered, the program can be switched to 
the privileged mode to allow execution of these instructions. Then, after the last privileged 
instruction in the set is encountered, the program can be returned to non-privileged mode. This 
bracketing of privileged instructions aids in reducing system violations, since the program cannot 
access locations or resources outside the user environment when it is running in non-privileged 
mode. 

Before running a temporarily-privileged program, you should understand how the central processor 
handles procedure calls (PCAL instruction) and exits (EXIT instructions) when encountered in 
either mode: 

In the privileged mode, when a PCAL instruction is executed, privileged mode is retained 
even though the destination code segment may have a non-privileged CST entry. When an 
EXIT instruction is encountered, the resulting mode depends on the status word in the 
stack marker. 

In the non-privileged mode, when a PCAL instruction is encountered, the mode assumed 
is obtained from the CST entry for the destination code segment. When an EXIT 
instruction occurs, the resulting mode is taken from bit of the status in the stack 
marker. If the entry indicates privileged mode, a system violation occurs. 

In general, the status word determines the action taken in privileged mode, but the CST determines 
the action in non-privileged mode. 

NOTE 

See the Machine Instruction Set Reference Manual for further 
discussions of the PCAL and EXIT instructions and System 
Reference Manual (Chapter 4) for principle of operation. 

A program is loaded and begins execution as a temporarily-privileged program (in the non-privileged 
mode) when these two conditions are met: 

1. The program is prepared with the Privileged Mode Capability, by entering the appropriate 
capability-class attribute in the caplist parameter of the :PREP or :PREPRUN command 
that prepares the program. This requires that you have been assigned the Privileged Mode 
Capability. 
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2. The NOPRIV parameter is included in the :PREPRUN or :PREP command that executes 
the program, or the CREATE intrinsic that creates a process «o run i*. 

When a temporarily-privileged program is initiated, the CST entries corresponding to its segments 
have their privileged-mode bits set off. 

If you possess Privileged Mode Capability, you also can call all intrinsics available to users with the 
Data Segment Management Capability (Section VIII), provided that you acknowledge these rules: 

1. When calling the data segment intrinsics from privileged mode, ensure that the DB register 
points to its normal stack position. When the GETDSEG intrinsic is used to create extra 
data segments under these conditions, the number of segments that can be created is 
limited only by the space available in the Process Control Block Extension. This number 
is virtually unlimited. 

2. When a temporarily-privileged process calls a data segment intrinsic while in 
non-privileged mode, the data segment index returned to the calling process also can be 
used by the process to reference that segment in privileged mode. If the process caUs a 
data segment intrinsic in privileged mode, however, the index returned cannot be used to 
reference the segment in non-privileged mode. 

ENTERING PRIVILEGED MODE 

The GETPRIVMODE intrinsic is used to switch a temporarily-privileged program from the 
non-privileged mode to the privileged mode. This intrinsic turns the privileged mode bit in the status 
register on, but leaves the privileged mode bit in the Code Segment Table entry for the executing 
segment off. Thus, if additional segments are to be run as part of the program, they will be run in 
privileged mode unless an intrinsic is specifically called to return to the non-privileged mode, 
because the status register rather than the Code Segment Table determines a mode change when 
running in privileged mode. 

Figure 9-1 contains a program that uses the GETPRIVMODE intrinsic to switch to privileged mode. 
Privileged mode is necessary temporarily because the program opens a file with both NOBUF and 
NOWAIT aoptions specified in the FOPEN intrinsic call. Privileged mode capability is necessary for 
this because your I/O could overwrite other data in the system unless caution is used. 

The program in figure y-i was prepared wim uie ^^.r - j. i*± ^oj.o.mc.^4. „ K v,v-*— — — 

command. This enables the program to be switched from non-privileged to privileged mode with the 
GETPRIVMODE intrinsic. The statement in the program 

GETPRIVMODE; 

switches the program from non-privileged to privileged mode before the next statement opens a file 
with both the NOBUF and NOWAIT aoptions specified. 

The statement 
CCG(2); 

causes the program to quit if a CCG condition code (signifying that the program already is running 
in privileged mode) is returned. 
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00001000 

00002000 

00003000 

00004000 

00005000 

00006000 

00007000 

00008000 

00009000 

00010000 

00011000 

00012000 

00013000 

00014000 

00015000 
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00017000 

00018000 

00019000 

00020000 

00021000 

00022000 

00023000 

00024000 

00025000 

00026000 

00027000 

00028000 

00029000 

00030000 

00031000 

00032000 
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00034000 

00035000 

00036000 

00037000 
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00039000 

00040000 

00041000 

00042000 

00043000 

00044000 

00045000 

00046000 

00047000 

00048000 

00049000 

00050000 

00051000 



00000 
00000 
00000 
00005 



00005 1 



00005 1 
00005 1 
00005 1 
00005 1 
00005 1 
00005 1 
00005 1 



00005 1 



00005 1 
00005 1 
00005 1 
00005 1 
00005 1 
00005 1 
00015 1 
00023 1 
00023 2 
00027 
00042 
00045 
00051 
00054 
00064 
00075 
00111 



00116 1 

00130 1 

00131 1 
00131 2 
00137 2 
00143 2 
00143 1 
00145 1 
00145 2 
00147 
00147 
00157 
00164 
00174 
00177 
00207 
00220 
00234 

00234 1 

00235 1 



SCONTPOL USLINIT 
BEGIN 

BYTE ARRAY OUTPUT(0|6) t«"OUTPUT " > 

BYTE ARRAY TNAMCO 163 ja"DATAIN " | 

BYTE ARRAY DEVCO I 7) l»"LP TERM »j 

INTEGER OUT, FILE, LGTH,Ii«-1,PR0MPT|b»T ",DONEl=Ol 

EQUATE MAXTRM=3» 

ARRAY BUFR(0:36«MAXTRM)| 

INTEGER ARRAY OPEN(OjMAXTPM) > 

DEFINE CCL a IF < THEN QUIT*, 

CCG a IF > THEN QUIT*, 

CCNEs IF <> THEN QUIT#J 

INTRINSIC FOPEN,FREAD,F«RITE,FCLOSE,GETPRlVMODE,GETUSERMOOE, 
IOWAIT,QUIT» 



00116 1 WAITt 



<<END OF DECLARATI0NS» 

0UT!*FQPEN(0UTPUT,4,i,,BEV)| CCIC13? 
WHILE tU»I+l)<MAXTRM DO 
BEGIN 

SET PR I V«ODE> XCG.t :2 ) f - - ^ 

FILE I "FOPEN ( TNAM , *405 , %4404 , 36 , DEV f 3 ) ) 

CCLC3)) 

CETUS£»«OCEf CC«<4Jt ::■'. 

OPEN(n»*FILEj 

FWRITE(FILE,PPOMPT,l,%320), CCNEC5)| 

IOWAITCFILE) i CCNEC63» 

FREADCFILE,BUFR(I#363,-72)( CCNE(7)| 
END» 



EXIT: 
:s%013| 



PRIMARY DB STORAGE 
NO. ERRORSaOOO) 
PROCESSOR TIMEaOjO0l02| 



FILE:=IOWAITCO,,LGTH)| CCLC8); 
IF > THEN 
BEGIN 

FCL05ECFILE, 0,0)| CCLC9)> 
IFCDONE»eDONE+l)>aMAXTRM THEN GO EXITi 
END 
ELSE 
BEGIN 
l:=-l> 
DO Hcl + l 

UNTIL OPENCDaFlLE OR laMAXTRHj 
IF IaMAXTRM THEN QUIT(10)| 
FWPITE(OUT,BUFR(I»36),-LGTH,0)| 
CCNEClDi 

FWRITE (FILE, PROMPT, 1,%320) I CCNEC12)) 
IOWAITCFILEJi CCNEC13); 

FREAD(FILE,BUFR(I#36),-72)> CCNEU4); 
END) 
GO TO WAITj 
END, 

SECONDARY DB STORAGE*tO0175 
NO. WARNINGSaOOO 
ELAPSED TIHEa0l00l08 



<<LINEPRINTER OUTPUT>> 
<<L0OP-SET UP TERMS>> 

i:<m Oft; wwm mpm»>:, 

>«DATA INPUT TERMINAL» 
<<CHECK FOR ERROP>> 

: .::*«FGB ■'MMm^t/Om .?;■:-:■ 
<<SAVE FILE NUHBERS» 
<<OUTPUT ? PROMPT>> 
«COMPLETE REQUEST» 
«INPUT DATA«NOWAIT» 



<<WAIT FOR 1ST DONE» 
«EOF ON TERM READ» 

«TERHINAL FILE>> 
«ALL TERMS CLOSEDT» 



«SET BUFFER INDEX» 
<<INCP BUFFER INDEX>> 
«SEARCH FOP FILE NO>> 
<<FILE NOT FOUND>> 
<<COPY INPUT TO LP» 
<<CHECK FOR ERROR» 
«OUTPUT ? PR0MPT>> 
«COMPLETE REQUEST» 
«INPUT DATA-NOWAIT>> 

<<C0NTINUE>> 



Figure 9-1. Using the GETPRIVMODE and GETUSERMODE Intrinsics 
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ENTERING NON-PRIVILEGED MODE 

The GETUSERMODE intrinsic is used to change a temporarily-privileged program from the 
privileged to the non-privileged mode. This intrinsic changes the privileged mode bit in the status 
register to off. 

The statement 

GETUSERMODE; 

in figure 9-1 illustrates this intrinsic call 

MOVING THE DB POINTER 

If you have the Data Segment Management Capability, and run a process with an extra data segment 
in privileged mode, you can prepare for movement of data between this segment and the stack with 
the SWITCHDB intrinsic. This intrinsic changes the DB register so that it points to the base of the 
extra data segment rather than the base of the stack. The SWITCHDB intrinsic returns the logical 
index of the data segment indicated by the previous DB register setting, allowing you to restore this 
setting later. If the previous DB setting indicated the stack, zero is returned. 

. i„ + ^ _-j. j.i-_ t»u „__:„4. 4-u.w- i+ nn^fa +/-> +Vio V>oca pf an ovtra rla+.a apsmpnt, whose 

As an exampie, to set me uo iegioi.ei ou ^um. m v umi,& •"-' u * iC ""^ ^* **" <=—.—« & >-- 

logical index is indicated in the word INDEX2, the following intrinsic call could be used: 

SET:=SWITCHDB(INDEX2); 

where INDEX2 is a logical value denoting the logical index of the data segment to which the DB 
register is switched, as obtained through the GETDSEG intrinsic call. MPE checks the value 
specified for this parameter to insure that the process has previously acquired access to this 
segment. For an extra data segment, this parameter must be a positive, non-zero integer; and to 
switch back to the stack, this parameter must be zero. 

The calling process is aborted if you try to call the SWITCHDB intrinsic from a program which does 
not have the Privileged Mode Capability. 

SCHEDULING PROCESSES 

Every process in the system has a priority assigned to it. When a process is ready to run, it is placed 
in the READY list. When the dispatcher runs, it selects for execution the process with the highest 
priority that is in memory. 

The master queue (see figure 9-2) is divided into logical areas, each corresponding to a particular 
type of dispatching and priority class for the processes within it. A logical area can be a linear 
subqueue, a circular subqueue, or a portion of the main master queue. In a linear subqueue, the 
process with highest priority accesses the central processor first and maintains this access until the 
process either is completed, terminated, or suspended to await the availability of a required 
resource. In a circular subqueue, all processes have equal priority and each accesses the central 
processor for an interval (time quantum) of maximum duration (or until completed, terminated, or 
suspended). At the end of this duration, control is transferred to the next process in the queue, 
continuing in a round-robin fashion. This time-slicing is controlled by the system timer. Processes 
that are not scheduled in a subqueue are scheduled in the master queue. 
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Figure 9-2. Queue Structure 



9-6 



Each linear subqueue in the master queue is defined by a single priority number, and each circular 
subqueue is defined by a range of priority numbers. While the standard user is aware of the priority 
class associated with a subqueue, only a user with System Supervisor or Privileged Mode capability 
can deal with priority numbers. The standard subqueues (priority classes) are as follows: 

AS Is a linear subqueue containing processes of very high priority. Its priority 

range is 30-99 and it is presently used only by MPE 

Scheduling Type: Linear 

Priority Range: 30-99 

BS Is a linear subqueue containing processes of very high priority. It is accessible 

to users having MAXPRI=BS. Normally, priority for a BS process is 100. 
However, by specifying a rank > in the CREATE or GETPRIORITY in- 
trinsics, the process may be set in the master queue at min (100 + rank, 149). 

CS Is a circular subqueue generally devoted to interactive sessions. A CS process 

whose CPU time between priority changes exceeds the "average short trans- 
action" will be lowered in priority, but not below the C Subqueue Priority 
Limit, called CLIMIT, which may be set by the :TUNE command. (See 
Section II of the System Manager/System Supervisor Reference Manual, 
dOuuu-yuux^.) 

Scheduling Type: Circular 

Priority Range: 150-CLIMIT 

DS Is a circular subqueue generally devoted to batch jobs. A DS process whose 

CPU time between priority changes exceeds the backgroundquantum will be 
lowered in priority, but not below the D Subqueue Priority Limit, or 
DLIMIT, which may be set by the :TUNE command. (See Section II of the 
System Manager/System Supervisor Reference Manual, 30000-90014.) 

Scheduling Type: Circular 

Priority Range: 150-DLIMIT 

ES Is a circular subqueue generally used for so-called "idle" processes. When an 

ES process's CPU time between priority changes exceeds the background- 
quantum, its priority is reduced, but not below ELIMIT. Such a process will 
have a minimal impact on the performance of processes in other subqueues. 
(See Section II of the System Manager/System Supervisor Reference Manual, 
Qnnnn.Qfini A \ 

Scheduling Type: Circular 

Priority Range: 150-ELIMIT 

In all cases, it should be remembered that low numeric values mean high priority in the system. 

The System Manager has the ability to modify on-line the values of the starting priority (BASE) and 
priority limits (LIMIT) for each queue, as well as the average short transaction limit and back- 
groundquantum via the :TUNE command. 
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A CS process is given a priority of CBASE when it begins. (See Figure 9-2). When a process stops 
(for disc I/O, terminal I/O, preemption, etc.), its new priority is determined so that it may be re- 
queued for the CPU. If the process has completed a transaction, (a transaction is defined as the time 
between terminal reads), the priority becomes CBASE. The value of an "average short transaction" 
is then recalculated. If the CS process has not completed a transaction, and if the process has ex- 
ceeded the average short transaction filter value since its priority was last reduced, the priority is 
decreased, but will not be worse than CLIMIT. 

DS and ES processes begin at DBASE and EBASE respectively, and are rescheduled according to 
the same criteria as used for CS processes, with the exception that a fixed value (the value of max 
which has been specified for the subqueue) is used in place of the average short transaction value, 
which is used for CS processes only. 

The priority class of a process can be specified by the normal user with standard or optional MPE 
capabilities. In the two-character string that comprises a priority-class reference, the first character 
refers to the location of a subqueue within the master queue (in alphabetical order) and the second 
character specifies whether the logical area is the subqueue itself (S) or the portion of the master 
queue (M) that immediately follows the subqueue. When a priority class is requested for a process, 
it is assigned the lowest priority within that class (relative to other processes already assigned the 
same class). In a circular subqueue, the actual priority of the process is modified as other processes 
use central processor time. 

Only a user with Privileged Mode Capability can assign a priority number to a process. Priority 
numbers range from 1 to 255 inclusively, with 1 denoting the highest priority. Any two processes 
having the same priority number are in the same subqueue. The privileged mode user also can 
specify the relative ranks of processes having identical numbers within a linear subqueue, and can 
assign them specific priorities in the master queue. 

Priorities are assigned to processes through the priorityclass parameter of the CREATE and/or 
GETPRIORITY intrinsic. Because users with the Privileged Mode Capability can schedule processes 
within the master queue, the priorityclass parameter can take on the following values: 

1. A string of two ASCII characters describing the standard priority-class (subqueue) in 
which the process is to be scheduled; the standard subqueues are "AS", "BS", "CS", 
"DS", or "ES". 

2. An ASCII character (x) specifying a valid subqueue, followed immediately by the 
single-character string "M", indicating the Master Queue. The word format is: 



BITS 



15 



'M" 



: 



This schedules the process in that region of the master queue directly adjacent to and 
below the subqueue x. The process is scheduled in the first available priority in that 
region. 
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An ASCII character (y) specifying an absolute priority number, followed by the single- 
character string "A" indicating that y is an absolute priority number. The word format 
is: 



BITS 



7 


8 15 


V 


"A" 



This schedules the process at the location specified by y in the Master Queue. If another 
process or subqueue already occupies the location designated by y, the process is placed 
in the first location available moving toward the ES subqueue, and the process priority 
number is changed to reflect that location. 
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By using MPE file system intrinsics, you can perform the following operations on files: 

Open files with FOPEN. See page 10-28. 

Request access and status information about a file with FGETINFO. See page 10-70. 

Request file error information with FCHECK. See page 10-74. 

Read records (or a portion of a record) from a file with FREAD (see page 10-48) and 

FREADDIR (see page 10-52). 

Write a record (or a portion of a record) to a file with FWRITE (see page 10-51) and 

FWRITEDIR (see page 10-55). 

Move a specific record from a file into a buffer preparatory to reading the record to the 

stack with FREADSEEK. See page 10-55. 

Initiate completion operations for an I/O operation with the IOWAIT intrinsic. See page 

10-63. 

Write a file label on a magnetic tape file. See page 10-93. 

Read a user-defined label from a disc file with FREADLABEL. See page 10-70. 

Write a user-defined label onto a disc file with FWRITELABEL. See page 10-66. 

Update a record on a disc file with FUPDATE. See page 10-60. 

Space forward or backward on a disc or tape file with FSPACE. See page 10-85. 

Reset the logical record pointer to any logical record in a fixed-length record disc file 

with FPOINT. See page 10-96. 

Perform control operations on a file (or the device on which the file resides) with FCON- 

TROL. See page 10-95. 

Activate and deactivate access mode options with FSETMODE. See page 10-96. 

Rename an open disc file with FRENAME. See page 10-45. 

Determine if an input file and a list file are interactive or duplicative with FRELATE. See 

page 10-97. 

Coordinate access to shared files with FLOCK and FUNLOCK intrinsics (see pages 

10-58 and 10-60). 

Close a file with FCLOSE. See page 10-40. 

FILE MANAGEMENT SYSTEM 

The File Management System provides a uniform method of directing input and output of 
information. It handles various input /output applications, such as the transfer of information to and 
from user processes, compilers, and data management subsystems. 

MPE treats each set of input or output information as a set of records arranged into a file. When a 
file is created, MPE allocates (or requests the operator to allocate) a device for its storage. Input 
read from a hardware device such as a card reader is accepted from that device. Similarly, output 
from an executing process is transmitted to the required device (such as a line printer). 

You reference a file by the file name assigned to the file when it is created. When you reference an 
existing file, MPE determines the device or disc address where the file is stored and accesses the file 
for you. In most cases, access to the file remains device independent. 
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The MPE File Management System allocates devices for the storage of files on the basis of 
specifications from you. For example, you can request a device by generic type name, or "device 
class", as configured by the System Manager (such as any magnetic tape unit or line printer), or by 
the logical device number that refers to a specific device. Logical device numbers are related to all 
devices when MPE is configured. 

FILE CHARACTERISTICS 

A file can contain MPE commands, programs, or data, or any combination of these elements, 
written in ASCII or binary code. 

Within a file, information is organized as a set of logical records, which are fields of data input, 
processed, and output as a unit. A logical record is the smallest data grouping directly addressable 
by you. Its length is specified by you when you create or define the file. A physical record is one or 
more logical records, and is the basic unit that can be transferred between main memory and the 
device on which the file resides. Physical records can be longer or the same size as the logical records 
in the file. In files on disc or magnetic tape, physical records are organized as blocks that always 
contain an integral number of logical records. On unit-record devices, the size of the physical rec- 
ords in a file is determined by the device. For example, each physical record read from a card reader 
consists of one punched card; each physical record written to a line printer consists of one line of 
print. On unit-record devices in multi-record mode, logical records are not blocked. For example, on 
punched cards, each logical record is assumed to begin at the first column of the card. Thus, to read 
a single 100-character logical record, the multi-record aoption must be specified in the FOPEN call 
to open the file. Then the record would be read as 80 characters from one card (physical record) 
and 20 characters from the next card. The next logical record is assumed to begin in the first col- 
umn of the third card encountered. Similarly, when a file is transmitted to a printer, each logical 
record appears as one line of print (physical record), left-justified. If the logical record is longer than 
the print line, and the multirecord aoption is specified, the remaining information is continued on 
the next line, also left-justified. 

Files of fixed or undefined length permit sequential or direct access. Variable length files permit 
sequential access only in buffered mode, and direct access only in NOBUF. 

MPE manages each file on disc as a set of extents. Each extent is an integral number of 
contiguously-located disc sectors. All extents (except possibly the last) are of equal size. When a file 
is opened, the first extent (containing at least one sector for file label information) is allocated 
immediately. Other extents, up to a maximum of 32, are allocated as needed. Alternatively, you can 
request immediate allocation of more than one extent when the file is opened. The size of each 
extent is determined as noted in the discussion of the :FILE command parameter numextents in the 
MPE Commands Reference Manual. 

Each extent of a disc file must be totally contained within a given disc device. In addition, the 
extents that comprise a disc file are restricted to disc devices that are members of the device class 
specified when the file was created. Normally, each extent is arbitrarily assigned to any device with 
this class. Alternatively, each extent may be restricted to a specific disc device. The method of 
extent allocation is determined by the device class specification of the FOPEN intrinsic when the 
file is created. 
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RECORD FORMATS 

A file can contain records written in one of three formats: fixed-length, variable-length, and 
undefined length. These formats are described below. (In all cases, recsize is in words.) 

For fixed-length records, physical records are blocks containing one or more logical records. The 
block size is determined by multiplying the block factor by the logical record size. (The block 
factor and logical record size are specified in the blockfactor and recsize parameters of the FOPEN 
intrinsic.) On any one file, fixed-length records are all the same size. A 128-word physical record 
(block) containing three 80-byte, fixed-length logical records is illustrated below: 

Physical Record 
(blockfactor x recsize) 



LOGICAL 
RECORD 


LOGICAL 
RECORD 1 


LOGICAL 
RECORD 2 


■ 



RECSIZE= -80 RECSIZE= -80 RECSIZE= -80 



120 WORDS 



8 WORDS UNUSED 



DISC SECTOR 



If you use a record of 129 words with a blockfactor of 1, you will waste 127 words of disc space, as 
follows: 



128 WORDS 




1WORD 127 WORDS UNUSED 



For optimum use of disc space, therefore, block size should be computed such that [recsize x 
blockfactor) modulo 128 = 0. 

bw „„ r inh!e-!enPth records (as for fixed-length records), physical records are blocks containing one 
or more logical "records - but, on any one file, the record size may vary from record to record and 
so the number of logical records per physical record may vary. Therefore, when the file is created, 
the block size is determined by multiplying the blockfactor by the recsize parameter specified in 
FOPEN plus one, and adding one word (reserved for file-system use). 

Because a fixed block factor has no meaning for a file of variable length records, once the calcula- 
tion is done the block factor is reset to 1. Maximum logical recsize is then set to actual blocksize 
minus two words. 

Actual Blocksize = (blockfactor x (recsize + 1))+1 
(in words) 
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In a block containing variable-length records, each logical record is preceded by a one-word 
byte-count showing the length of that record in bytes. The last record in the block is followed by a 
word containing "-1", acting as the block terminator; the next logical record encountered will be 
the first record in the next block. (Logical records are not split across block boundaries.) The block 
format is : 



Physical Record 
[(blockfactor x (recsize + 1) + 1] 



BYTE 
COUNT 



LOGICAL 
RECORD 



BYTE 
COUNT 



LOGICAL 
RECORD 1 



BYTE 
COUNT 



LOGICAL 
RECORD 2 



Unless block size is computed such that 

(actual block size) modulo 128 = 0, 
some disc space will be wasted. 

For example, if recsize = 128 words and blockfactor = 1, 126 words of disc space will be wasted as 
follows: 

-1 

X 



COUNT 



127 WORDS 



1 WORD 126 WORDS UNUSED 



For undefined-length records, physical records and logical records are synonymous— that is, 
Physical record A is the same as logical record A. For records of this type, the recsize parameter 
specified by the user denotes the size of the longest record to be transferred. The format of 
undefined records written to disc, with respect to the disc sectors occupied, can be illustrated by 
three cases in which the user-specified recsize is 256. 

Case 1: You write a record 256 words long. The full record completely fills two disc sectors. 



SECTOR A 



RECSIZE = 256 



X 



SECTOR B 
— -*- 



RECORD 



t 



WORDS WRITTEN = 256 



Case 2: 



You write a record 129 words long. The record written occupies all of sector A and 
the first word of sector B; the last word written is propagated throughout the 
remainder of sector B. (The rule is: if (reclength) modulo 128 is not zero, then the 
last word written is propagated through the current sector.) 
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RECS1ZE = 256 






SECTOR A 


SECTOR B 








i 






RECORD 


1 

(-»► 

1 












1 





CONTENT OF WORD 129 

PROPAGATED THROUGH 

SECTOR B 



WORDS WRITTEN = 129 



Case 3: You write a record 127 words long. The record written occupies 127 words of 
Sector A; the last word of the record is propagated throughout the remainder (word 
128) of Sector A. Sector B contains uninitialized data. (The rule is: any sector not 
written into will remain uninitialized to (binary files) or blanks (ASCII files).) 



RECSIZE = 256 



SECTOR A 



RECORD 



CONTENT OF WORD 127 

PROPAGATED THROUGHOUT 

SECTOR A 



SECTOR B 



UNINITIALIZED 
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RELATIVE I/O BLOCK FORMAT 



Item 

#23 



Item 

#24 



Logical Record < 






Logical Record F-l 



Active Record Table 



Item 

#22 



i [ Item 
,,#25 



Item 

#21 



FFILEINFO Item Numbers (see Figure 2-1A) 

Item 21 — Physical Block Size 

22 - Data Block Size 

23 — Offset to Data in Blocks 

24 — Offset to Active Record Table within the block 

25 — Size of Active Record Table 

Active Record Table 



I I I I I I I I I I I I I I I 



I I I I I I I I I I I I I I I 



0123456789012345 

A = active-record table size in words = Lrd 

F = blocking factor (number of records per block) 

R = index of desired record, modulo F 

W = index of word for desired record = R/16 

P = index of bit for desired record = R mod 16 

bit = 0: inactive record 
= 1 : active record 



record <p (block-relative) 
record 15 



word 



word A-l 
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FILE DEVICE RELATIONSHIPS 

Devices required by files are allocated by MPE. You can specify these devices by type (such as any 
card reader or line printer), or by a logical device number related to a particular device (such as a 
specific line printer). (A unique logical device number is assigned to each device when the system is 
configured.) Regardless of what device a particular file resides on, when a user program asks to read 
that file, it references the file by its formal file designator. MPE then determines the device on 
which the file resides, or its disc address if applicable, and accesses it for you. When the user pro- 
gram writes information to a particular file to be output on a device such as a line printer, again the 
program refers to the file by its formal file designator. MPE then automatically allocates the re- 
quired device to that file. Throughout its existence, every file remains device-independent; that is, it 
is always referenced by the same formal file designator regardless of where it currently resides. The 
user program always deals with logical records. 

NON-SHARABLE DEVICE ACCESS 

The specification of a device by type when a file is opened implies a request for the initial allocation 
of a previously unopened device. The file system, during FOPEN, issues an allocation request to the 
console operator. After the operator answers, FOPEN continues execution. (The device speci- 
fication is ignored when $STDIN[X] and $STDLIST are opened.) A job may reallocate an opened 
device by specifying the device's logical device number when the file is opened. In this case, no con- 

-.«1« nnnvniAt* iMfonTpM+mn ic rprmirprl 

Multiple processes can asynchronously interleave accesses to reallocated devices. Since the file 
system does "anticipatory reads" on buffered input devices, multiple processes should specify 
Multi-Access (better) or Inhibit Buffering (NOBUF) if records must be transmitted in the same 
order as requested. 

FILE DOMAINS 

The set of all permanent disc files in MPE is known as the system file domain. Within this domain, 
files are assigned to accounts and organized into groups under those accounts. You log on using an 
account and group which provides the basis for your local file references. You may be required to 
supply passwords for the account and group to log on, but thereafter (if the default MPE file 
security provisions are in effect) you can: 

• Have unlimited access to any file within your log-on or home group. If, however, the file 

• _ j_ j.„j i , „ 7^^u,..^-»^ tt/mi mnoT Vnnw fViic lonkwrvrd _ 

IS pruutjuueu uy a. iu l; masks i t*, jww m^v «.**« TT w ~~*» - 

• Read, and execute programs residing in, any file in the public group of your account, and 
in the public group of the system account. 

Potentially, if the MPE file security provisions at the account, group, and file levels were all 
suspended,' and you knew all account and group names and file lockwords, you could access any 
permanent file in the system once you logged on. Note that once you log on, you do not need to 
know the passwords for other accounts and groups to access files assigned to them - you only need 
to know their account and group names. But, if any of these files are protected by a file lockword, 
you must know this lockword. 

For every job or session running in the system, MPE recognizes another file domain, called the job 
or session file domain. This domain contains all temporary files opened and closed within the job or 
session without being saved (i.e., declared permanent). Files in these domains are deleted when the 
job or session terminates (if they are job/session temporary files), or when the creating program 
ends (if they are regular temporary files). 
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FILE LABEL 

MPE reads and writes file labels for files on disc during allocation of the devices on which the files 
reside. The format and content of file labels is presented in Appendix B. 

FILE ACCESSING 

You access files through commands and intrinsic calls. Commands, described in the MPE Commands 
Reference Manual, are issued external to the user program and perform administrative functions, 
such as creating, deleting, or renaming a file. Files are opened (through the FOPEN intrinsic); 
operated on through various intrinsics that read information from them, write information to them,' 
update them, or otherwise manipulate them; and, finally, they are closed (through the FCLOSE 
intrinsic). 

Within a program, a file is accessed by its formal file designator. The formal file designator is the 
name by which the program recognizes the file. This is the name supplied by the program to the 
FOPEN intrinsic.) At the time a file is FOPENed, this formal file designator is used to determine 
the actual file designator. The actual file designator is the name of the actual file to be used and the 
physical device upon which it resides, as recognized throughout the system by MPE. Thus, the 
actual file designator is an execute-time redefinition of the file specified in the program by the 
formal file designator. If you do not specify an actual file designator for a formal file designator, 
MPE uses the formal file designator for the actual file designator. 

MPE recognizes actual file designators for four types of files: 

• System-Defined Files 

• User Pre-Defined (Back-Referenced) Files 

• New Files 

• Old Files 

You can specify any of these designators programmatically. 

NOTE 

For discussions of MPE commands referenced below, such as 
:JOB, :DATA, :EOJ, :EOD, :FILE, and :BUILD, see the 
MPE Commands Reference Manual. 

RELATIVE I/O 

In addition to the conventional direct and serial access, MPE offers Relative I/O access. RIO is 
intended for use primarily by COBOL II programs; however you can access these files by programs 
written in any language. 

RIO is a direct access method that permits individual file records to be deactivated. These inactive 
records retain their space and position within the file, i.e., their relative position. 

RIO files may be accessed in two ways; RIO access and non-RIO access. RIO access ignores the 
inactive records when the file is read serially using the FREAD intrinsic; however such records can 
be read by direct access using FREADDIR. They may be overwritten both serially and directly 
using FWRITE, FWRITEDIR or FUPDATE. With RIO access the internal structure of RIO blocks 
is transparent. 
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Non-RIO access is provided to facilitate the replication of RIO files. This method requires 
knowledge of the internal structure of the file and is intended primarily for system use. Non-RIO 
access is enabled by specifying NOBUF I/O when the file is opened. 

Most of the existing MPE file intrinsics access RIO files in the same manner as they would access 
other MPE files. There are exceptions, however. Some of these are: 

FREAD inputs an active record, not necessarily the next physical record. 

FREADDIR inputs the specified record regardless of its activity state; a warning will result if the 
record is inactive 

FDELETE deactivates the next record, not the last-accessed record as defined by COBOL II. 

The actual size of a block will be slightly larger than the size specified when the file was built. 
The value returned by FGETINFO for blksize will depend on how the RIO file is being accessed. 

The amount of space available for user labels also may be slightly larger; this depends on the size 
of an extent which itself depends on the block size. 

SYSTEM-DEFINED FILES 

System-defined file designators indicate those files that MPE uniquely identifies as standard 
input/output devices for a job/session. They are referenced as follows: 



Actual File Designator 

$STDIN 



Device/File Referenced 

A file name indicating the standard job or session input device (that 
from which the job or session is initiated). For a job. this is typically a 
card reader. For a session, this is typically a terminal. Input data images 
in the $STDIN file should not contain a colon in column 1, since this 
indicates the end-of-data. (When data is to be delimited, this should be 
done through the :EOD command, which performs no other function.) 
Once : or :EOD is detected on $STDIN, that end-of-file condition is 
considered permanent for the life of the process. No further reading 
may be done from $STDIN/$STDINX by that process. [If :EOF: (hard- 
ware EOF command) is encountered, the end of file condition applies 

4-^ +u,r. nnfivn c-opcvij-*n TnrViir»V> will +-hcm Vinvp t.n terminate*. 1 
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Actual File Designator 



Device/File Referenced 



$STDLIST 
$NULL 



$STDINX Equivalent to $STDIN, except that records with a colon in column 1 

encountered in a data file are read without indicating the end of data. 
However, the commands .JOB, :DATA, :EOJ, :EOD and :EOF: are 
exceptions that always indicate the end-of-data. 

A file name indicating the standard job or session listing device 
(customarily a printer for a batch job and a terminal for a session). 

The name of a non-existent "ghost" file that is always treated as an 
empty file. When referenced as an input file by a program, that program 
receives an end-of-data indication upon each access. When referenced as 
an output file, the associated write request is accepted by MPE but no 
physical output is actually performed. Thus, $NULL can be used to 
discard unneeded output from a running program. 

USER PRE-DEFINED (BACK-REFERENCED) FILES 

A user pre-defined file is any file that was previously defined or re-defined in a :FILE command. In 
other words, it is a back-reference to that :FILE command. It is referenced by the following file 
designator format: 



*formaldesignator 
formaldesignator 



The name used in the formaldesignator parameter of the :FILE 
command. 



NEW FILES 



New files are files that have not yet been created, and are being created/opened for the first time by 
the current program. New files can have the following actual file designators: 



Actual File Designator 



$NEWPASS 



filereference 



File Referenced 

A disc file that is always assumed to be new, and is always closed in 
such a way that it can be automatically passed to any succeeding MPE 
command/job step within the same job/session, which will reference it 
by the file name $OLDPASS. Only one $OLDPASS file can exist in the 
job/session at any one time. (When $NEWPASS is closed, it is auto- 
matically changed to $OLDPASS, and any previous file named 
$OLDPASS in the job/session is deleted.) 

Requests that a new file be created with this name, residing on disc, or 
some other device. Unless other action is taken, a new disc file will be 
deleted on termination of the creating program. If closed as a job/ 
session temporary file, as shown later in this section, such a file is 
purged at the end of the job/session. If closed as a permanent file, it is 
saved until purged by you. Typically, this format consists of a file name 
containing up to eight alphanumeric characters, beginning with a letter, 
as discussed below. In addition, other elements (such as a group name, 
account name or lockword) can be specified. 
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OLD FILES 



Old files are existing named files presently in the system. They may be named by the following 
designators: 



Actual File Designator 

$OLDPASS 

filereference 



File Referenced 

The name of the temporary file resulting from the last close of a 
$NEWPASS file. 

Any other old file to which you have access. (The filereference format 
is discussed below.) It may be a job/session temporary file created in 
this or a previous program in the current job/session, a permanent file 
saved by any program, or a permanent file built (with the :BUILD 
command) in any job/session. 



INPUT/OUTPUT SETS 



All file designators described previously can be classified as those used for input files (Input Set) 
and those used for output files [Output Set). These sets are defined as follows: 



Input Set 
$STDIN 

$STDINX 

$OLDPASS 
$NULL 

*formaldesignator 
filereference 

Output Set 
$STDLIST 
$OLDPASS 

$NEWPASS 
$NULL 

*formaldesignator 
filereference 



The job/session input device. 

The job/session input device with records containing : in column 1 
allowed, (exclusive of :EOD, :EOJ, :DATA, etc.) 

The last $NEWPASS file closed, (considered a "passed file"). 

A constantly-empty file that will return an end-of-file indication 
whenever it is read. 

A back-reference to a previously-defined file (via :FILE command). 

A file name, and perhaps account and group names and a lockword. 
When file name, group name and account name are supplied, the name 
is said to be a fully qualified file name. 



The job/session listing device. 

The last $NEWPASS file closed, (considered a "passed file"). 

A new temporary file to be passed. 

A constantly-empty file that returns a successful indication whenever 
information is written to it. 

A back-reference to a previously-defined file. 

A file name, and perhaps account and group names and a lockword. 
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ACCESSING FILES ALREADY IN USE 

When a user process attempts to access a file already being accessed by another process, the action 
taken by MPE depends on the current use of the file, as shown in figure 10-1. 

Within a user program, the accessing and modification of files is requested through intrinsic calls. 
Each file referenced is first opened with the FOPEN intrinsic call. Then other operations, such as 
reading, writing, updating, and spacing forward or backward, can be performed on the file with 
other intrinsic calls. Finally, the file is closed with the FCLOSE intrinsic call, issued by the user 
process or (if not included in the user program) by MPE when the user process terminates. 

If you are programming in SPL, you declare the intrinsics and write the intrinsic calls as you do 
other statements within your program. If you are programming in another language, however, such 
as FORTRAN, any intrinsics required are called automatically by MPE (intrinsics may be called 
directly from other languages and the methods are described in the manuals covering the languages). 

In the FOPEN intrinsic call, you reference a particular file by its formal file designator. When the 
FOPEN intrinsic is executed, it returns to your program a file number by which the system 
uniquely identifies the file. The file number, rather than the file designator, is used by subsequent 
intrinsics in referencing the file. In an SPL program, you obtain this number through the normal 
conventions of the language. One such convention employs an SPL assignment statement to store 
the file number into a location specified by an identifier (name) which then can be used as an 
intrinsic call parameter to reference the file. The format of the assignment statement is discussed in 
the SPL Reference manual. Each intrinsic is declared and called as described in Section II. 

The condition codes returned to your program by the file system intrinsics have the following 
general meanings. The specific meanings, of course, depend on the particular intrinsic and are 
described in Section II. 

Condition Code Meaning 

CCE The function requested by the intrinsic call was completed 

successfully. 

CCG MPE encountered the end of the file while servicing the request. 

CCL MPE could not service the request because an error occurred. 

Corrective action may be taken in some cases. (By issuing an 
FCHECK intrinsic call, you can have a more detailed error 
description transmitted to your process.) If, however, the error 
resulted from invalid parameters supplied by you in the intrinsic call, 
the error is fatal and the process is aborted, or a software error trap, 
if previously enabled by you, is activated (See the XSYSTRAP 
intrinsic). 

When a file is accessed by a process running a program written in a language other than SPL, the file 
is generally (but not always) referenced by a file name. All intrinsic calls needed for opening, 
accessing, and closing the file are generated automatically by the user process, and the file name is 
equated with the file number used by the intrinsics to reference the file. 
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Figure 10-1. Actions Resulting from Multiple Access of Files 



When a new file is opened but not yet closed, it is always local to the process. At this time, the 
file name assigned by you need not be unique. But if the program tries to save the file permanent or 
job temporary (via FCLOSE), MPE determines whether another file with the same designator name 
exists in the domain in which you are trying to save that file (permanent or job temporary). If a 
name conflict occurs, a CCL condition code is returned to the user process from FCLOSE and the 
specific error is made available through the FCHECK intrinsic. When a program aborts, old files are 
returned to the domain in which they were found when opened; new files are deleted. The fact 
that a duplicate file name is detected at FCLOSE (not FOPEN) time is important for many 
applications. 

NOTE 

All intrinsics discussed in this section, with the exception of 
FOPEN, FGETINFO, FFILEINFO and FRENAME, can 
be called with the DB register pointing to a data segment 
other than the calling process' stack (split stack). All para- 
meters referenced in any calls to these intrinsics are always 
accessed using the current DB-register setting. Privileged 
mode is required to enter split-stack mode; once in split- 
stack mode, you need not remain in privileged mode to call 
File System intrinsics. 

Before a user process can read, write on, or otherwise manipulate a file, the process must initiate 
access to that file by opening it with the FOPEN intrinsic call (see page 10-28). This call applies to 
files on all devices. When the FOPEN intrinsic is executed, it returns to the user process the file 
number used to identify the file in subsequent intrinsic calls. 

If the file is opened successfully (and the CCE condition code results), the file number returned is a 
positive integer ranging from 1 to 255. (Theoretically, one process may open a maximum of 255 
files.) If the file cannot be opened, resulting in the CCL condition code, the file number returned is 
zero. Whenever a process is run, MPE calls FOPEN twice to open $STDIN and $STDLIST for that 
process before any of the user code is executed. Thus there are 253 file numbers available to the 
user process. However, no assumption should ever be made concerning the allocation order of these 
file numbers. 

If a process issues more than one FOPEN call for the same file before it is closed, this results in 
multiple, logically-separate accesses of that file, and MPE returns a unique file number for each such 
access. Also, MPE maintains a separate logical record pointer (indicating the next sequential record 
to be accessed) for each access where the multi-access option was not requested or not permitted at 
FOPEN time. 

In opening a file, FOPEN establishes a communication link between the file and your program by 
• Determining the computer system on which the file resides. 



• 



Allocating to your program the device on which the file resides. If the file resides on 
magnetic tape, FOPEN determines whether it is present in the system. (If it is not, 
FOPEN requests the system operator to supply the tape. Cataloging of tapes, however, is 
not done.) Generally, disc files can be shared concurrently among jobs and sessions. But 
magnetic tape and unit-record devices are allocated exclusively to the requesting job or 
session. For example, different processes within the same job may open and have con- 
current access to files on the same magnetic tape or unit-record device; but this device 
cannot be accessed by another job until all accessing processes in this job have issued 
corresponding close requests (FCLOSE calls). 
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Verifying your right to access the file under the security provisions existing at the ac- 



count, group, and file levels. 



• Determining that the file has not been allocated exclusively to another process (by the 
exclusive option in an FOPEN call issued by that process). 

• Processing file labels (for files on disc). For new files on disc, FOPEN specifies the 
number of labels to be written. 

• Allocating to the file the number of extents initially requested (for new disc files). 

• Constructing the control blocks required by MPE for this particular access of the file. The 
information in these blocks is derived by merging specifications from five sources, listed 
below in descending order of precedence: 

1 The file label, obtainable only if the file is an old file on disc. This information 
overrides that from any other source. (Label formats are presented in Appendix B). 

2. FOPEN overrides of incompatible options. 

3 The parameter list of a previous :FILE command referencing the same formal file 
designator named in this FOPEN call, if such a command was issued in this job or 
session. This information overrides that from the two sources listed next. 

4. The parameter list of this FOPEN intrinsic call. 

5. System default values provided by MPE (when values are not obtainable from the 
above three sources). 

When information in one of these five sources conflicts with that in another, pre-empting 
takes place according to the order of precedence shown above. To determine the 
specifications actually taking effect, the user can call the FGETINFO/FFILEINFO intrin- 
sic, described later in this section. Notice that certain sources do not always apply or 
convey all types of information. (For instance, no file label exists when a new file is 
opened and so all information must come from the last four sources above.) 

FILES ON NON-SHARABLE DEVICES 

When a process opens a disc file, you specify whether the file is an old or new file; an old file is an 

existing labeled file, and a new me implies tnat me me is tu uc ^ a ^. ..i.™ ~ *~ — — 

file that resides on a non-sharable device, the device's attributes may override your old/new 
specification. Specifically, devices used for input only (such as card readers) automatically imply 
old files; devices used for output only (such as line printers) automatically imply new files; serial 
input/output devices (such as teletype terminals and magnetic tape units) follow your old/new 
specifications. 

When a job attempts to open an old file on a non-sharable device, MPE searches for ■the , file in the 
Virtual Device Directory (VDD). If the file is not found, a message is transmitted to the console 
operator, asking him to locate the file by taking one of the following steps: 

1. Indicate that the file resides on a device that is not in auto-recognition mode. No :DATA 
command is required - the operator simply allocates the device. 

2. Make the file available on an auto-recognizing device, and allocate that device. 

3. Indicate that the file does not exist on any device; the user's FOPEN request will be 
rejected. 10-15 



When a job opens a new file on a non-sharable device (other than magnetic tape), the operator is not 
required to intervene. In these cases, the first available device is used. (A non-sharable device is con- 
sidered directly available if it is not being used, or if it is being used by the requesting job and is 
requested by its logical device number.) 

The specification of a device class when FOPEN is issued implies a request for the initial allocation 
ot a previously unopened device. (The device parameter is ignored when $STDIN(X) and $STDLIST 
are opened ) A job may reallocate an opened device by specifying the device's logical device number 
when the file is opened. The FGETINFO/FFILEINFO intrinsic shonld h* u -h *~ **—;- - 
logical device number assigned to an opened file. The subsequent FOPEN which supplies ^logical 
device number should insure that no existing file equation overriding the device number is acci- 
dentally picked up. 

When a job opens a new file on a magnetic tape unit, operator intervention is always required- the 
operator must make the tape available. 

SPECIAL CONSIDERATIONS FOR SHARED FILES 

When a file is being shared among two or more processes, or within the same process, and is being 
written to by one or more of them, care must be taken to ensure that the processes are appropri- 
ately interlocked. For example, if Process A is trying to read a particular record of the file and at 
ttiat time Process B should execute and try to write that record, the results are not predictable 
Process A may see the old record, the new record, or hash consisting of parts of both. If buffering is 
being done, please bear in mind that an output request (FWRITE) will not cause physical I/O to 
occur until a block is filled, which typically will contain several records. A process trying to read 
such a file could, for example, read past the last record of the file which has been written on the 
disc because the end-of-file pointer is not kept in the file but is kept in core where it can be updated 
quickly as writes occur. This interlocking is provided by the intrinsics FLOCK and FUNLOCK 
which use a Resource Identification Number (RIN) as a flag to interlock multiple accessors. 

For processes within a job/session sharing a file in multi-access mode, the use of a local RIN is 
recommended instead of FLOCK and FUNLOCK. That recommendation does not apply if the file 
is simultaneously being accessed from another job or session. 

In the simple case of a file shared between a writer process and a reader process, where the writer is 
merely addingrecords to the file, the writer calls FLOCK prior to writing each record and FUNLOCK 
after writing. The reader calls FLOCK prior to reading record, and FUNLOCK after reading If the 

^"r ShOUld GXeCUte WhUe the reader is in the middle of a rea d. the writer will be impeded 
on its FLOCK call until the reader signifies that it is done by calling FUNLOCK. Similarly if the 
reader should execute while the writer is performing a write, the reader will be impeded on its 
FLOCK call until the writer calls FUNLOCK. FUNLOCK ensures that all buffers are posted on the 
disc so that reading processes can see all the data. 

Protection offered by FLOCK and FUNLOCK depends on cooperation among all processes ac- 
cessing the file. If one process does not use FLOCK, or uses it improperly, problems will arise. 
More complicated cases arise when a file has two or more writing processes, or when the write con- 
sists of writing more than one record at a time. If, for example, it should be necessary to write pairs 

c^FLOCK^bef ^f 1 r ntil *** """" ° f ^ ^ m ***»' the ™^ P*>— n 

caU FLOCK before writing the first record of the pair, and FUNLOCK after writing the second 

This procedure also can be used if the records are to be written in different files; one of the files is 

used as a sentinel" file and the processes FLOCK and FUNLOCK this file as required. 
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PRIVATE VOLUMES SUBSYSTEM 

Users with the Volume Set Usage (UV) capability can maintain files on private disc volumes. These 
private volumes consist of removable disc packs, which, when mounted on a disc drive, can be 
accessed by MPE through the MPE Private Volumes Subsystem. 

Individual removable volumes can be combined to form logical units in the form of volume sets or 
volume classes. 

See the MPE Commands Reference Manual for a further discussion of the Private Volumes Sub- 
system. 

Whether disc files created by you will be assigned to a private disc volume set or the system volume 
set depends on how the file group for your account was established by the System Manager. The 
System Manager can establish your file group so that disc files created by you will be stored on a 
private home volume set or on the system volume set. In either case, you do not need to be con- 
cerned with, or even aware of, where disc files created and opened by you will be stored. 

If your file group has been structured to use the Private Volumes Subsystem, then when you create 
a new disc file with the :BUILD command (see the MPE Commands Reference Manual) or the 
FOPEN intrinsic, MPE checks to determine if your home volume set is mounted. If your home 
volume set is not mounted, MPE asks the Console Operator to mount it. The only indication to you 

«-P -J-Uifi nsvf-is-ii* is +"U«->+ tr/viiv wA/nrnw itnll crtic>r\£±inA i-P trAiiv Vi r»m a «a1iiwq <3A+ ic nrt-r rr»/-\Tm+*aH Tin -HI it 
til Ull© OtCuiOll LO LU.1CIU y\J\AJ. £JXvJgXCU.XX ¥V±il OUO^CtlU, XX. jf V/ WJL AX\jrxx*v- »l/iuinC EC u J.B j.±v/ w ihi/wmivu) m-i-imx j.w 

is mounted by the Console Operator. Similarly, when you close and save a disc file with the 
FCLOSE intrinsic, it is automatically stored on your home volume set or the system volume set, 
depending on how your file group was established, again with no action necessary from you. 

HOW TO USE FILES 

The remainder of this section explains what you can accomplish with files using the file system 
intrinsics. An attempt is made to show practical applications for the intrinsics, instead of merely 
reiterating the purpose of each intrinsic (which was discussed in Section II). 

INTERNAL OPERATIONS FOR FILE ACCESSING 

Before a file can be used, it must be opened with the FOPEN intrinsic. If you are programming in 
SPL, you must call the FOPEN intrinsic from your program. The compilers for other languages, 
such as FORTRAN and COBOL, call the FOPEN intrinsic and open the file for you. In any case, 
however, whether called explicitly by your SPL program or called for you in a FORTRAN or 
COBOL program, the FOPEN intrinsic is used to open all files in a program. Several items which 
should be considered before using FOPEN are discussed in the following paragraphs. 

For example consider what occurs when a user coding a program in SPL performs a call to the 
FOPEN intrinsic to open a new disc file. A new disc file is a file that has not existed previously in 
the system. One of the fundamental things that occurs at FOPEN time is that an access interface is 
created for the file. This access interface may be an extra data segment that is created and which 
contains information about the file. In addition, a buffer space is allocated in this file segment to 
contain the number of records per block that the user has specified in the FOPEN call. The buffer 
space is large enough to receive a block of information from the disc. 

The file segment is pointed to by an entry in the user's stack. This entry is called an available file 
table (AFT) and is part of the process control block extension (PCBX) in the user's stack. Upon the 
successful completion of an FOPEN call, an integer value is returned to the calling program. This 
integer value is an entry into the AFT, and the appropriate AFT entry in turn then points to the file 
segment that belongs to this particular file. 
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Figure 10-2 shows the stack and the AFT entry pointing to the file segment. The file segment 
contains buffers, in this case, enough room for three logical records. In the example shown in figure 
10-2, each record is 80 bytes and the records are grouped into a block of three. Thus, there is 
enough room in the file segment to hold three logical records. 



STACK 



FILE SEGMENT 



AVAILABLE FILE 
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OPEN FILE 



FILE INFORMATION 
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RECORD NO. 1 
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SYSTEM < 
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(ENTRY MADE AT 

FCLOSETIME) 



BLOCKS 
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RECORD 



RECORD 



80 BYTES 
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wsmmhwa i 6 bytes left 

OVER 



Figure 10-2. File Access Interface for New Disc Files 
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The next thing that occurs is that file space is allocated to the file. On the system disc there is a 
table of free space that is monitored by MPE. The file system refers to the file space table and 
allocates initial space for this file, (the number of sectors allocated depends on the parameters 
specified in the FOPEN call), by deallocating free space from the table and writing a file label in 
the first sector of the newly allocated space. The file system then deallocates the free space and 
writes a file label in the first sector of the free space. 

A partial list of items contained in a disc file label is shown below. Once their values are established, 
they cannot be changed by subsequent FOPEN operations. 

File name 

Sector address 

Maximum number of logical records 

Logical record size 

Block size 

Foptions (Exception: disallow file equations bit) 

Number of extents 

Extent size 

File code 

The linkage then, goes from the user's stack, via the available file table, to the file segment; from 
the file segment there is a pointer to the label on the disc itself. In the simplified example of figure 
10-2, the file label is shown on the system disc, however, it could be on any disc in the system. 

Since this is a new file, there is no information in the file. Therefore the access mechanism is the 
only information the system has for this file. 

Depending on the FOPEN parameters specified, it is possible to write on this file. The example 
shows 80-byte records, three records per block, and one buffer. If an FWRITE intrinsic were called 
to write a single 80-byte record, that record would be moved from the user's stack to position 
number 1 in the file segment. As soon as that physical move from the stack to the file segment is 
complete, the FWRITE also is complete as far as the program is concerned. However, no actual 
write to the disc takes place. An FWRITE call to write record number 2 would consist of a move 
from the stack to the file segment and record number 2 would occupy position number 2 in the file 
segment. Subsequently, record number 3 would occupy position 3 in the file segment. Immediately 
upon the file segment being full, that is, when the third record has been written to the file segment, 
the entire block of information is then transferred to the disc. Thus, when the file system is used in 

i _ -a 11-. _„„ ~,„a -iv^w. +v>o cs+ci^V +<-> +Vip filp spcrmpnt. 

a buffered manner witn disc iues, recorus atLuauj cue muv<=« ""■" »«- »•— — — o > 

then when the last record in a block has been moved into the file segment, a physical write to the 

disc occurs in a block fashion. That is, a whole block of information (in this case containing three 

records) is transferred to the system disc. 

It is at FCLOSE time that you decide whether you want the file to remain in the system as a 
permanent file or a job/session temporary file, or whether you want the file to be deleted from the 
system. 

At FCLOSE time, the access interface is dismantled and therefore if information about the file is to 

be saved in the system, the FCLOSE intrinsic is used to close the file with a permanent disposition. 

The name of the file, which is available to the system in the file label, is posted in the system 

j; „-x „„j„. „„,,, w_<™ o™™,n+ and crrmirv MPE finds that area of the directory and posts an 

entry in the system directory for that file name. If the name is FILE1, then FILE1 resides on the 

disc at a certain sector address. Referring to figure 10-2, you can see that in the system directory 

there will be an entry that consists of the file name and some sector address, for example, 123. The 

sector address 123 then points to the label. 
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As soon as the entry is made in the system directory, consisting of the name of the file and a 
pointer to the file label, then the FCLOSE operation continues and the file access interface is 
dismantled. The file segment is deleted from the system and the entry in your stack in the available 
file table (AFT) is purged. If the FCLOSE specifies the save permanent disposition, the name of the 
file will be placed in the system directory with a pointer to the file label. 

As soon as the FCLOSE operation is complete, then, the disc file becomes a permanent file in the 
system, or, to use different terminology, it becomes an old disc file. If a file with the name of 
FILE1 already exists in your log-on account and group, it is not noticed until FCLOSE is issued 
and, at that time, results in an error. ' 

Figure 10-3 shows that now there is an entry in the system directory with a file name of FILE1 and 
a sector address of 123. To open this file, as an existing, or old file, the FOPEN parameters would 
have to be changed to specify an old file. Then the same type of operation that occurred before 
would occur again with one exception: since an existing file is being opened, it is not necessary to 
deallocate free space, what is necessary is for the system to establish a mechanism for the user stack 
area. In other words, the system makes an entry in the available file table, and creates another file 
segment, pomting to the existing file on the disc. 

Figure 10-4 shows what occurs if an FOPEN call is issued for an old file named FILE1. In this case 
FOPEN specifies an old file and must supply the name of this file; then MPE searches the system 
directory under the appropriate account and group for this file. Once the file is found, MPE then 
establishes the access mechanism, consisting of a file segment as before, and a pointer from the file 
segment to the file label on the disc. 

The other type of old file is the job or session temporary file. One of the differences between a job 
temporary file and a permanent file is where the actual entry is placed when the file is closed Each 
job or session has a table called the job temporary file directory. In the case of a file that is saved 
with temporary disposition, the name of the file and a pointer to the file label are stored in this job 
temporary file directory. (Note that the job temporary file directory is unique to each job or 
session.) Another difference between a job temporary file and a permanent file is that when a 
job/session terminates, all job/session temporary files are deleted from the system, and file space 
that was held by such files is returned to the system. 

File characteristics are obtained from different sources, depending on whether the file is a new disc 
me, an old disc file, or a file on a device other than disc. 

For a new disc file, the characteristics are established as shown below: 

FOPEN: 

(create a new disc file) 

The characteristics are obtained from: 



FOPEN intrinsic parameters 
and defaults 



overridden by: 



:FILE command parameters 
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Figure 10-3 File Name and Sector Address Storage 

A disc file and a file label are created according to the characteristics specified above. (This 
label remains with the file during its entire existence on the system.) 

For an old disc file, the characteristics are established as follows: 

FOPEN: 

(open existing disc file) 
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Figure 10-4. File Access Interface for Old Disc Files 



The characteristics are obtained from: 



FOPEN intrinsic parameters 
and defaults 



overridden by : 



: FILE command parameters 



overridden by 



Disc file label 



The existing file can be either an old temporary file or an old permanent file. 
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When a file is opened on a device other than disc, the file characteristics are established as follows: 

FOPEN 

(open a device file) 

The characteristics are obtained from: 



FOPEN intrinsic parameters 
and defaults 



overridden by : 



:FILE command parameters 



overridden by : 



Device-dependent restraints 
imposed by the file system. 



Note that if you have the ND (non-sharable device) capability, the file system allows you to open a 
physical I/O device in the same manner as you would open a disc file. (Discs are the only devices 

which are considered Dy mm to oe simuitancOuSiV ancuauie aiuvug s^»^<** ^c.-., .* - 

non-sharable device has been FOPENed, it is referred to as a devicefile. The physical characteristics 
of each different device available to the file system can differ substantially and these differences 
affect the characteristics which are permitted for corresponding device files. For this reason, the file 
system imposes a number of device-dependent restrictions on device files. Card reader files, for 
example, are required to have read-only access with a block factor of one. A summary of these 
restrictions is presented in table 1 0-1. 

It also should be noted that some non-sharable devices can be spooled by MPE. This means that 
data input from and output to such devices is stored temporarily on the disc in transit from the 
physical devices to and from the user program. Because data can be temporarily buffered in a disc 
file, the program assumes that all physical device files which it requires are constantly available to it. 
Input data typically is read and stored before a program requires it, and output data is delayed until 
the program's file operations are complete (at FCLOSE time). Other than these external variations, 
most differences between a spooled and a non-spooled device file are insignificant to the program. 

One exception, however, may affect applications which write very large reports. Regardless of the 
spooled device, there is a limit as to how much disc space an individual spoolfile can have. In some 
cases, it is possible to exhaust this maximum space allowed. As an example, an application would 
not normally expect to encounter an end-of-file condition when writing to a line printer. Yet this 
may actually happen if the line printer is spooled and the report being written is large enough to 
have reached the spoolfile's limit. Therefore, applications should check for end-of-file after every 
write. When an end-of-file condition is detected, the output file should be closed and a new one 
opened. 

NOTE 

The maximum size of a spoolfile in sectors is 32* configured 
extend size for spoolfiles. (The maximum number of extents 
is 32.) A configured extent size of 384 sectors means the 
spoolfile has room for approximately 25,000 lines. 
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Table 10-1. Device-Dependent Restrictions 



INPUT ONLY DEVICES (SERIAL) 

Card Reader/Paper Tape Reader 



No carriage control 
Undefined-length records 

If card reader, ASCII only (can only read ASCII cards without using FCONTROL) 

Blockfactor = 1 

Domain = 1 (OLD permanent) 

If not ASCII, then NOBUF 

If access type = 1, 2, 3, then access violation results 

INPUT/OUTPUT DEVICES (PARALLEL) 

Terminals 

ASCII 
NOBUF 

Undefined-length records 
Blockfactor = 1 

INPUT/OUTPUT DEVICES (SERIAL) 

Magnetic Tape Drive 
Serial Disc Drive 

No restriction 

OUTPUT ONLY (SERIAL) 

Line Printer/Card Punch/Paper Tape Punch/Plotter 

If Line Printer, ASCII only 

Undefined-length records 

Blockfactor = 1 

Domain = NEW 

Access Type = 1, write only (if read only specified, access violation results) 

UNDEFINED (COMMON CHECKING) 

If carriage control specified and not ASCII, access violation results 
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Table ±u-z. uiassmcation 01 uevices 



DEVICE NAME 


DEVICE TYPE 
NUMBER (OCTAL) 


CLASSIFICATION 


Moving-Head Disc 


00 


NEW or OLD 


Fixed-Head Disc 


01 


NEW or OLD 


Card Reader 


10 


OLD only 


Paper Tape Reader 


11 


OLD only 


Terminal 


20 


NEW or OLD 


Printing Reader Punch 


24 


NEW or OLD 


Hardwired Serial Interface 


23 


NEW or OLD 


Synchronous Single-Line Controller 


26 


NEW or OLD 


Magnetic Tape Drive 


30 


NEW or OLD 


Line Printer 


40 


NEW only 


Card Punch 


41 


NEW only 


Paper Tape Punch 


42 


NEW only 


Plotter 


43, 44, 45 


NEW only 



An alternative to generating one large output spoolfile is to periodically close the output file and 
open a new one. A large report program might start a new output file every 200 pages. While this 
technique requires gathering several files for the complete report, it has the advantage of allowing 
the first portion of the report to print while the program is still running. 

When a non-sharable device file is opened, the device has to be allocated by the system so that the 
calling process can access the file. MPE classifies devices as OLD or NEW, OLD only, or NEW only, 
depending on the device type. Table 10-2 shows the manner in which devices are classified. Included 
in table 10-2 is the device name, its octal device number, and whether it is considered to be 
OLD/NEW, OLD only, or NEW only. 

The flowchart shown in figure 10-5 illustrates how MPE allocates a non-sharable device when an 
FOPEN request is received. 

First, MPE considers the device type requested by the FOPEN call. If the device type is input only, 
this is considered to be an OLD file. Because MPE considers the file to be an OLD file, it searches 
for a pre-defined input file. For example, a file identified with a :DATA command. If no such file is 
found, MPE sends a message to the Console Operator asking for the logical device number of the 
input device. 



10-25 



START ) 



INPUT ONLY 



SET 

ACCESS «- READ ONLY 
DOMAIN^ OLD 




OUTPUT ONLY 



INPUT/OUTPUT 



WRITE ONLY 



ALL OTHER 
ACCESS MODES 



SEARCH DEVICE 
DIRECTORIES FOR THE 
READY OR OPENED 
DEVICE SPECIFIED 





ACCESS <- WRITE ONLY 
DOMAIN «- NEW 




ASK OPERATOR TO 
IDENTIFY THE DEVICE 




''DEVICE: DATAV. NO 
^ACCEPTING ? 



ASK OPERATOR TO 
IDENTIFY THE DEVICE 
INO MESSAGE IF 
REALLOCATION FOR 
CURRENT DEVICE OWNER! 




GET OPERATOR REPLY 
TO FORMS MESSAGE 



ALLOCATE THE DEVICE 

TO THE REQUESTOR 



Figure 10-5. Device Allocation Flowchart 



If FOPEN specified a device type that is considered by MPE to be output only, MPE considers this 
to be a NEW file. Normally, NEW files do not require special attention. If the device is available, it 
will be allocated to the user. Printer forms message, plotter, or magnetic tape requests are the 
exceptions, however, and require operator intervention. 

If a device was specified that is an input/output type of device, MPE next considers the user access 
requested in the FOPEN call. If read only was requested, the file is considered to be an OLD file. If 
write only, MPE considers the file to be a NEW file. 

If the FOPEN call requested a user access of input/output, or any other mode (except read only or 
write only), MPE next looks at the type of file domain specified in the call (NEW or OLD) and 
opens the file accordingly. The system device directories contain entries for each device that 
contains a file. Non-spooled devices can have only one file (for example, a card deck in the read 
hopper of a card reader), but spooled devices can have several file entries (for example, card decks 
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which have been read in by the device and are stored as spoolfiles on disc to await access). Such 
device files are identified by :DATA commands. Information from a :DATA command image is 
used to build the device directory entry and identifies the file by file name, user name, and account 
name The data file may be accessed by a user program when its request matches the :DATA 
information and the file is in the READY state. In the case of an unspooled card reader, this means 
that only the -DATA card has been read in, and the rest of the deck awaits processing. In the case 
of a spooled card reader, however, this means that the :DATA card and the entire deck have been 
read and await processing in the form of a disc spoolfile. 

If the entry in the device directory indicates that the device is OPENED, a user process has already 
FOPENed the device file successfully (device or spoolfile). In this case, access to the same non- 
sharable device is granted only if the requesting process is in the same process tree as the process 
which has the file open. This is accomplished by referencing a logical device number, not a device 
classname. These subsequent calls to FOPEN will not require operator intervention - the first de- 
vice allocation request is the only one issued to the operator. This technique might be used by a 
program which does a great deal of magnetic tape processing but wants to avoid multiple tape allo- 
cation messages. Attempts to use this technique with a non-spooled printer can result m inter- 
mixing of output data. 
A condition code error is returned to the calling process if: 

1 Device type specified an input only device and requested access was write only. 
2. Device type specified an output only device and the requested access was read only. 

A message to the operator will be printed if: 

1. The device is a card reader and a pre-defined file (read in with a :DATA card) cannot be 
located to match the file requested. 

2. The device is a magnetic tape device. 

3. The device is a plotter. 

4. The device is a line printer and uses the forms message option. 

OPENING FILES 

OPENING A NEW DISC FILE 

Figure 10-6 contains an SPL program which opens two files: a card reader file and a new disc file. 

The second FOPEN call in figure 10-6. 

OUT:=FOPEN(OUTPUT,%4,%101,128); 
opens the new disc file. The parameters specified are 

formaldesignator DATAONE, which is contained in the byte array OUTPUT. 

%4, for which the bit pattern is as follows: 



foptions 






1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 









































1 




































4 





Bits 

Binary 

Octal 
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PAGE 0001 HEWLET 


00001000 


00000 


00002000 


00000 


00003000 


00000 1 


00004000 


00005 1 


00005000 


00004 1 


00006000 


00005 1 


00007000 


00005 1 


ooooeooo 


00005 1 


00009000 


00005 1 


00010000 


00005 1 


00011000 


00005 1 


00012000 


00005 1 


00013000 


00005 1 


00014000 


00012 1 


00015000 


00013 1 


00016000 


00013 2 


00017000 


00015 2 


00018000 


00017 2 


00019000 


00017 1 


00020000 


00017 1 


00021000 


00030 1 


00022000 


00031 1 


00023000 


00031 2 


00024000 


00033 2 


00025000 


00035 2 


00026000 


00035 1 


00027000 


00035 1 


00026000 


00035 1 


00029000 


00043 1 


00030000 


00044 1 


00031000 


00044 2 


00032000 


00046 2 


00033000 


00050 2 


00034000 


00050 1 


00035000 


00051 1 


00036000 


00051 1 


00037000 


00056 1 


00038000 


00057 1 


00039000 


00057 2 


00040000 


00061 2 


00041000 


00063 2 


00042000 


00063 1 


00043000 


00063 1 


00044000 


00066 1 


00045000 


00066 1 


00046000 


00066 1 


00047000 


00072 1 


00048000 


00073 1 


00049000 


00073 2 


00050000 


00075 2 


00051000 


00077 2 


00052000 


00077 1 


PRIMARY DB STORAGE 


NO. FRRORS»000| 


PROCESSOR TIMExOlO 



HEWLETT-PACKARD 32100A.05.1 SPL/3000 THE. OCT 7. 1975. 10130 AM 



SCONTROL USLINIT 

BEGIN 

BYTE ARRAY INPUT ( I6M «»INFILE "I 
BYTE ARRAY DEV ( !4) »»»CARD '•» 
BYTE ARRAY OUTPUT (0: 7) !=»DATAOME "I 
ARRAY BUFFER(0»127>* 
INTEGER IN.OUT.LGTHt 



INTRINSIC FOPEN.FREAD.FWRITE.FCLOSE. PRINT 
<< END OF DECLARATIONS >> 

INJ»FOPEN(INPUT,%5..40.DEV) I 
IF < THEN 
BEGIN 

PRINT«FILE'INFO<IN> I 
QUITO) I 
END! 

OUTI«FOPEN(OUTPUT,*4,*101, 128)1 

If < THEN 

BEGIN 111#1P€ ;< ; 

PR f «T » F It£ « ! W 1 ou n i 

QUIT12H 
ENOI 

COPYtLOOPJ 

LGTHJ=FREADUN. BUFFER, 40) I 
IF < THEN 
BEGIN 

PRlNT«FILE«INFO(IN) I 
QUITO) I 
END! 
IF > THEN GO ENO'OFIFILEI 

FWRITEtOUT. BUFFER. LGTH.O) I 
IF <> THEN 
BEGIN 

PRlNT«FILE»INFO(OUT) I 
OUITU) I 
END I 



GO COPYtLOOPl 

END'OF'FILEI 

FCLOSEtOUT.«11.0) » 
IF < THEN 
BEGIN 

PRINT'FILE'INFO(OUT) I 
QUIT(5) » 
ENDI 
END. 
=«007» SECONDARY DB STORAGE*«00213 

NO. WARNINGSsOOO 
0J03I ELAPSED TIMEaO«00!44 



•FILE«INFO,QUIT» 



<<CARD READER>> 
<<CHECK FOR ERROR>> 

<<PRINT ERROR>> 
<<ABORT>> 



•rot** &15-C *IL£>* 



<<REA0 A CARD>> 
<<CHECK FOR ERROR>> 

<<PRINT ERROR>> 
<<ABORT>> 

«CHECK FOR EOF>> 

<<COPY CARD TO DISC>> 
<<CHECK FOR ERROR>> 

<<PRINT ERROR>> 
<<ABORT>> 



<<CONTINUE COPYING>> 



<<MAKE PERMANENT>> 
<<CHECK FOR ERROR>> 

<<PRINT ERROR>> 
<<ABORT>> 



Figure 10-6. Opening a New Disc File 
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aoptions 



The above bit pattern specifies the following file options: 

Domain: New file, no search of system or job temporary file directory 
is necessary. Bits (14:2) = 00. 

ASCII/Binary: ASCII. Bit (13:1) = 1. 

%101, for which the bit pattern is as follows: 






1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 





























1 

















1 


















1 













1 





Bits 

Binary 

Octal 



The above bit pattern specifies the following access options: 

Access Type: Write access only. Bits (12:4) = 0001. 
Exclusive: Exclusive access. Bits (8:2) = 01. 



All other parameters are omitted from the FOPEN intrinsic call. 

Once the file is opened, the file number (used by other file system intrinsics when referencing this 
file) is returned to the variable OUT. 

The condition code is checked with the 

IF < THEN 

statement. If the condition code is CCL, signifying that the FOPEN request was denied, the next 
four statements, starting with the BEGIN statement, are executed. 

The statement 

PRINT' FILETNFO(OUT); 

calls the PRINT'FILE'INFO intrinsic, which prints a FILE INFORMATION DISPLAY on the 
standard list device, enabling you to determine the error number returned by FOPEN. The 
parameter (OUT) specifies the file number returned through the FOPEN intrinsic. If the file was not 
opened successfully, OUT = 0, where specifies that the FILE INFORMATION DISPLAY will 
reflect the status of the file referenced in the last call to FOPEN. See Section X for a discussion of 
the FILE INFORMATION DISPLAY 

The QUIT intrinsic call 

QUIT(2); 

aborts the process. The parameter (2) is an arbitrary user-supplied number. When a QUIT intrinsic is 
executed, this number is printed as part of the resulting abort message, allowing you to determine, 
in the case of multiple QUIT intrinsic calls in a program, which specific QUIT call was executed. 
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NOTE 

The QUIT intrinsic causes MPE to close all files with no 
change. Thus, new files are deleted, old files are saved and 
assigned to the same domain to which they belonged 
previously. 

OPENING AN OLD DISC FILE 

Figure 3-7 contains an SPL program that opens three files: an old disc file, $STDIN and 
$STDLIST. ' 

The statement 

DFILEl:=FOPEN(DATAl,%5,%345,128): 

opens the old disc file. The parameters specified are 

formaldesignator DATAONE, which is contained in the byte array DATA1. 

foptions %5, for which the bit pattern is as follows: 






1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 
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The above bit pattern specifies the following file options: 

Domain: Old permanent file, the system file directory should be 
searched. Bits (14:2) = 01. 
ASCII/Binary: ASCII. Bit (13:1) = 1. 

%345, for which the bit pattern is as follows: 
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The above bit pattern specifies the following access options: 

Access Type: Update access. (This file is updated later in the program 
with the FUPDATE intrinsic.) Bits (12:4) = 0101. 
Multirecord: Non-multirecord mode. Bit (11:1) = 0. 
Dynamic Locking: Dynamic locking allowed. Bit (10:1) = 1. 
Exclusive: Share access. Bits (8:2) = 11. 
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SCONTROL USLINIT 
BEGIN 

BYTE ARRAY DATA1 (0 : 7) : ="DATA0NE " » 

ARRAY BUFFER(0:127) I 

INTEGER DFILE1.LGTH.DUMMY.IN.LISTI 

INTRINSIC FOPEN.FRE AD. FUPD ATE. FLOCK, FUNLOCK.FCLOSE, 
PRINT' FILE 'INFO.QUIT.FWRITE.FREAD; 

PROCEDURE FILERROR(FILENO.OUITVO) » 
VALUE QUITNOI 
INTEGER FILENO, QUITNOI 
BEGIN 

PRINT 'FILE' INFO (FILENOM 

QUIT(QUITNO) » 
ENDt 



<<END OF DECLARATIONS>> 

t.FIL'l := c '0PLNiE)ATAl,tK.*^4 5.13SM 

if < itift* fkfphom::)«-ilf;.i> t 

IN:=FOPEN( .$244) ? 

IF < THEN FILERR0R!IN.2> ? 

LIST:=F0PEN!.%614»%1) » 

IF < THEN FILERRORILIST.3) i 

UPDATE'LOOP: 

FLOCK(OFILEl.l) I 

IF < THEN FILFRRORIDFILE1.4) I 

LGTH ! = FRE AD < OF ILE1* BUFFER ,128) 8 
IF < THFN FILERROR(OFILEl,5i I 
IF > THEN GO END'OF'FILEI 

FWRITF ( LIST, BUFFER »-20,«320! I 
IF <> THEN FILERR0R!LIST,6) » 

DUMMY t =FRE AD (IN, BUFFER (30) .5) J 
IF < THEN FILERR0RIIN.7) » 
IF > THFN GO END'OF'FILEI 

FUPDATE(DFILE1. BUFFER. 128) ! 

IF <> THEN FILERR0R(DFILE1»8) t 

FUNLOCK(DFILEl) J 

IF <> THEN FILERR0R(DFILE1»9) J 

GO UPDATE'LOOPI 

END'OF'FILE: 

FUNLOCK(DFILEl) I 

IF <> THEN FILERROR(DFILEltlO) I 

FCLOSE(DFILEl.O.O) » 
IF < THEN FILERROR(DFILEl.ll) I 
END. 
n%007» SECONDARY DB STORAGE=%00204 

NO. WARNINGS=000 
0J03J ELAPSED TIME=0:00:17 



llliiillillllllllllll 

«fHFf< TOR f<H--.(i» 

<<$STDIN>> 

<<CHECK FOR FRROR>> 

<<SSTDLIST>> 
<<CHECK FOR ERROR>> 



<<LOCK FILE/SUSPEND>> 
<<CHECK FOR ERROR>> 

<<GFT EMPLOYEE RECD>> 
<<CHECK FOR FRROR>> 
<<CHECK FOR EOF>> 

<<EMPLOYEE NAME>> 
<<CHECK FOR ERROR>> 

<<EMPLOYFF NUMBER>> 
<<CHECK FOR ERROR>> 



<<EMPLOYEE RECORD>> 
<<CHECK FOR FRROR>> 

<<ALLOW OTHER ACCESS>> 
<<CHECK FOR ERROR>> 

<<CONTINUE UPDATE>> 



<<ALLOW OTHER ACCESS>> 
<<CHECK FOR ERROR>> 

<<DISP-NO CHANGF>> 
<<CHECK FOR ERROR>> 



Figure 10-7. Opening an Old Disc File 
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All other parameters are omitted in the FOPEN intrinsic call. Note that for existing files FOPEN 
will return a lockword violation (FSERR92 via FCHECK) if the lockword is not included in the 
formaldesignator parameter. 

Once the file is opened, the file number (used by other file system intrinsics when referencing this 
file) is returned to the variable DFILE1. 

The condition code is checked with the statement 

IF < THEN FILERROR(DFILEl,l); 

If the condition code is CCL, the error- check procedure FILERROR (see statements 10 through 16 
in the program) is called and two parameters, DFILE1 and 1, are passed to it for FILENO and 
QUITNO (see statement number 10). DFILE1 contains the file number (assigned to it when the 
FOPEN intrinsic opened the file) to be passed by FILENO, and 1 represents an arbitrary 
user-supplied number to be passed by QUITNO. 

The FILERROR procedure passes the file number (through FILENO) to the PRINT 'FILE 'INFO 
intrinsic. If the file was not opened successfully, FILENO = 0, where specifies the status of the 
file referenced in the last call to FOPEN. The PRINT 'FILE 'INFO intrinsic prints a FILE 
INFORMATION DISPLAY on the standard output device, enabling you to determine the error 
number returned by FOPEN. See Section X for a discussion of the FILE INFORMATION 
DISPLAY. 

The QUIT intrinsic call (statement 15) 

QUIT(QUITNO); 

aborts the program's process. The value of QUITNO is 1 and this number is printed as part of the 
resulting abort message, allowing you to determine, in the case of multiple QUIT intrinsic calls in a 
| program, which specific QUIT call was executed. The system Job Control Word "JCW" is set to 
FATAL1 in this example. 

FOREIGN DISC FACILITY 

The Foreign Disc Facility (FDF) allows you to use the file system to access and alter disc packs and 
flexible diskettes that do not have standard HP 3000 file system disc label formats. When mounted, 
a disc volume with an unrecognizable disc label is assumed to be a foreign disc. 

Discs and diskettes must be physically compatible with HP hardware. The IBM 3741 format dis- 
kettes (64 words per sector), for example, are compatible. 

When using the FOPEN intrinsic to open a foreign disc file, the recsize is forced to 128 words (IBM 
diskettes are forced to 64 words). The file system will treat disc sectors as file records, thereby 
allowing you to manipulate the foreign file as though it was an MPE created file. 

In addition to FOPEN, several other intrinsics have been modified to accommodate foreign discs. 
I They are: FCLOSE, FREAD, FWRITE, FWRITEDIR, FREADDIR, FGETINFO, FFILEINFO and 
FCHECK. 
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OPENING A FILE ON A DEVICE OTHER THAN DISC 

Figure 10-8 contains an SPL program that opens a card reader file and a disc file, reads the contents 
of a card deck and writes the records read from the card deck into the disc file and, finally, closes 
the disc file as a permanent file. 

NOTE 

If a card deck is read in by the spooler before the program 
which references the deck executes, the system finds an entry 
for the card reader file in the device directory and allocation 
is automatic. If the card deck is not read before the program 
executes, however, the system will print a message on the 
system console requesting the Console Operator to reply with 
the logical device number of the device on which the file 
resides. 

The NOT READY message was printed because the read 
hopper of the card reader was emptied by the spooler when 
the INFILE deck was read. 

In figure 10-8, the statement 

IN:=FOPEN(INPUT,%5„40,DEV); 
calls the FOPEN intrinsic to open the card reader file. The parameters specified are 
formaldesignator INFILE, which is contained in the byte array INPUT. 

foptions %5, for which the bit pattern is as follows: 
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aoptions 



recsize 
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The above bit pattern specifies the following file options: 

Domain: Old permanent file, system file domain. Bits (14:2) = 01. 
ASCII/Binary: ASCII. Bit (13:1) = 1. 

Omitted. All bits are set to zero, access defaults to READ only. 
40 words. 

CARD. The byte array DEV, containing the string "CARD", is 
specified for the device parameter. 



All other parameters are omitted in the FOPEN intrinsic call. 
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PRIMARY DB STORAGE= 
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PROCESSOR TIMEs 
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SCONTROL USLINIT 

BEGIN 

BYTE ARRAY INPUT ( 16) : «»INFILE "I 
BYTE ARRAY DEV (0 !4) »s»CARD "I 
BYTE ARRAY OUTPUT (0 J 7) S=»DATAOME »« 
ARRAY BUFFER<0>127>» 
INTEGER IN.OUT.LGTHJ 

INTRINSIC FOPEN.FREAD.FWRITE.FCLOSE, 

<< END OF DECLARATIONS >> 

iNt »FOP£N < mPtjX*%*r , ,*o ,0 E v> * 
IF < TH£N 
BEfilN 

PRINT'FILF'INFOUNH 
SUIT CI H 

OUT I xFOPEN (OUTPUT. «4.«10 1,128)1 
IF < THEN 
BEGIN 

PRINT«FlLE«INFO<OUT) I 
QUIT<2> I 
END! 

COPY* LOOP J 

LGTHI=FREAD(IN. BUFFER, 40) « 
IF < THEN 
BEGIN 

PRINT'FILE'INFOUN) I 
QUITO) » 
END I 
IF > THEN GO END'OFtFILEl 

FWRITEIOUT. BUFFER. LGTH.O) I 
IF <> THEN 
BEGIN 

PRlNT»FILE«INFO(OUT) I 
QUITI4) t 
END! 

GO COPY»LOOP» 

END'OF'FILEI 

FCLOSE(OUT.%11.0) I 
IF < THEN 
BEGIN 

PRINT»FlLE»INFO(OUT) I 
0UIT(5) « 
END! 
END. 
*007» SECONDARY DB STORAGE*%0021 3 

NO. WARNIN6S=000 
8031 ELAPSED TIME=OI00144 



PRINT > FILE 'INFO, QUI T» 



<<CHECK FOR ERROR>> 
<<PR!NT £RROR» 



<<NEW DISC FILE>> 
<<CHECK FOR ERROR>> 

<<PRINT ERROR>> 
<<ABORT>> 



<<READ A CARD>> 
<<CHECK FOR ERROR>> 

<<PRINT ERROR>> 
<<ABORT>> 

<<CHECK FOR EOF>> 

<<COPY CARD TO DISC>> 
<<CHECK FOR ERROR>> 

<<PRINT ERROR>> 
<<ABORT>> 



<<CONTINUE COPYING>> 



<<MAKE PERMANENT>> 
<<CHECK FOR ERROR>> 

<<PRINT ERROR>> 
<<ABORT>> 



Figure 10-8. Opening a File on a Device Other Than Disc 
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Once the file is opened, the file number (used by other file system intrinsics when referencing this 
file) is returned to the variable IN. 

The next statement in the program 

IF < THEN 

checks the condition code. If the condition code is CCL, signifying that the FOPEN request was 
denied, the next four statements, starting with the BEGIN statement, are executed. 

The statement 

PRINT'FILE'INFO(IN); 

calls the PRINT'FILETNFO intrinsic, which prints a FILE INFORMATION DISPLAY on the 
standard list device, enabling you to determine the error number returned by FOPEN. The 
parameter (IN) specifies the file number returned through the FOPEN intrinsic. If the file was not 
opened successfully, IN = 0, where specifies that the FILE INFORMATION DISPLAY will reflect 
the status of the file referenced in the last call to FOPEN. See Section X for a discussion of the 
FILE INFORMATION DISPLAY. 

The QUIT intrinsic call 

QUIT(l); 

aborts the process. The parameter (1) is an arbitrary user-specified number. When a QUIT intrinsic 
is executed, this number is printed as part of the resulting abort message, allowing you to 
determine, in the case of multiple QUIT intrinsic calls in a program, which specific QUIT call was 
executed. 

ISSUING FREAD AND FWRITE INTRINSIC CALLS FOR $STDIN AND $STDLIST 

If the standard input device ($STDIN) and standard list device ($STDLIST) are opened with the 
FOPEN intrinsic, then FREAD and FWRITE intrinsic calls can be used with these devices. For 
example, the FREAD intrinsic can be used to transfer information entered from a terminal to a 
buffer in the stack; and the FWRITE intrinsic can be used to transfer information from a buffer in 
the stack directly to the standard list device. 

OPENING $STDIN. Figure 10-9 contains a program that opens $STDIN so that FREAD intrinsic 
calls can be issued directly against the standard input device (a- terminal in this case; the program 
was run interactively). 

The standard input device is opened with the FOPEN intrinsic call 

IN:=FOPEN(,%244); 

The parameters specified in the above intrinsic call are as follows: 

formaldesignator Omitted. 

Default: A temporary, nameless file that can be read, but not saved, is 
assigned. 
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SCONTROL USLINIT 
BEGIN 

BYTE ARRAY DATA1 ( S 7) : ="DATAONE "I 

ARRAY BUFFER (0! 127) I 

INTEGER DFILE1,LGTH,DUMMY,IN,LISTI 

INTRINSIC FOPEN, FRE AD, FUPD ATE, FLOCK, FUNLOCK.FCLOSE, 
PR INT 'FILE «INFO. QUI T . FWRITE .FREADJ 

PROCEDURE FILERROR(FILENO,OUITM0> I 
VALUE QUITNOI 
INTEGER FILENO, QUITNOI 
BEGIN 

PRINT 'FILE 'INFO (FILENO) « 

QUIT(OUITNO) ? 
ENDI 



PRIMARY DB STORAGE 
NO, FRRORS»000l 
PROCFSSOR TIME=0:0 



<<END OF DECLARATIONS>> 

DFILE1:=F0PEN(DATA1,%5,*34 5.128) I 
IF < THFN FILERROR(DFILEl.l) » 

IF < THEN FILERR0H(IN,2)I 

L!STi*F0PEN(.%6l4.*l) I 

IF « fHf>u FILERR0R(LIST.3)I 

upoatE'loop: 

FLOCK(DFILEl.l) » 

IF < THEN FILFRR0R(DFILE1,») » 

LGTH!=FREA0!DFILE1, BUFFER, 128) I 
IF < THFN FILERR0R(DFILE1,5U 
IF > THEN GO END»OF»FILEl 

FWRITF(LIST,BUFFER«-20,«320) ; 
IF <> THEN FILERR0R(LIST,6) I 

DlJMMYI=FREAD(IN,BUFFER(30> ,5) I 
IF < THFN FILERRORf IN,7) I 
IF > THEN GO END'OF'FILEl 

FUPDATEtDFILEl, BUFFER, 128) I 
IF <> THEN FILERR0R(DFILE1»8) I 

FUNLOCK(DFILEl) I 

IF <> THEN FILERR0R(DFILE1»9) J 

GO UPDATE'LOOPJ 

END«OF«FILE: 

FUNLOCK(DFILEl) I 

IF <> THEN FILERRORIDFILE1.10) » 

FCLOSE(DFILtl,0,0) » 
IF < THEN FILERROR(OFILEl.ll) I 
END. 
»*007» SECONDARY DB STORAGE=%00204 

NO. WARNINGS=000 
0103! ELAPSED TIME=0:00:17 



<<OLD DISC FILE>> 
<<CHECK FOR FRROR>> 

<<*STDLIST>> 

«cntcf fop f^»no»> 



<<LOCK FILE/SUSPEND>> 
<<CHECK FOR ERROR>> 

<<GET EMPLOYEE RECD>> 
<<CHECK FOR FRROR>> 
<<CHECK FOR EOF>> 

<<EMPLOYEE NAME>> 
<<CHECK FOR ERROR>> 

<<EMPLOYFF NUMBER>> 
<<CHECK FOR ERROR>> 



<<EMPLOYEE RECORD>> 
<<CHECK FOR ERROR>> 

<<ALLOW OTHER ACCESS>> 
<<CHECK FOR ERROR>> 

<<CONTINUE UPDATE>> 



<<ALLOW OTHER ACCESS>> 
<<CHECK FOR ERROR>> 

<<DISP-NO CHANGF>> 
<<CHECK FOR ERROR>> 



Figure 10-9. Opening $STDIN and $STDLIST 
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foptions 



%244, for which the bit pattern is as follows: 
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The above bit pattern specifies the following file options: 

Domain: New file, no search of system or job temporary file directory 

is necessary. Bits (14:2) = 00. 

ASCII/Binary: ASCII. Bit (13:1) = 1. 

Default Designator: $STDIN. Bits (10:3) = 100. 

Record Format: Undefined length. Bits (8:2) = 10. 

aoptions Omitted. All bits are set to zero, access defaults to READ only. 

All other parameters are omitted in the FOPEN intrinsic call. 

Once the file is opened, the file number (used by other file system intrinsics when referencing this 
file) is returned to the variable IN. 

The next statement in the program 

IF < THEN FILERROR(IN,2); 

checks the condition code. If the condition code is CCL, signifying that the FOPEN request was 
denied, the error-check procedure FILERROR is called. 

The FILERROR procedure (see statements 10 through 16 in the program) calls the 
PRINT'FILETNFO intrinsic, which prints a FILE INFORMATION DISPLAY on the standard list 
device, enabling you to determine the error number returned by FOPEN. 

The QUIT intrinsic call (statement number 15) aborts the process. 

OPENING $STDLIST. In figure 10-9, the statement 

LIST:=FOPEN(,%614,%l); 

opens the standard list device so that the FWRITE intrinsic can be used to transfer information 
directly to the device. 

The parameters specified in the above intrinsic call are 



formaldesignator 



Omitted. 

Default: A temporary, nameless file that can be written on, but not 

saved, is assigned. 
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foptions 



%614, for which the bit pattern is as follows: 
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The above bit pattern specifies the following file options: 

Domain: New file, no search of system or job temporary file directory 

is necessary. Bits (14:2) = 00. 

ASCII/Binary: ASCII. Bit (13:1) = 1. 

Default Designator: $STDLIST. Bits (10:3) = 001. 

Record Format: Undefined length. Bits (8:2) = 10. 

Carriage Control: Carriage control character expected. Bit (7:1) = 1. 

%1, for which the bit pattern is as follows: 






1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 















































1 






























1 





Bits 

Binary 

Octal 



The foregoing bit pattern specifies the following access options: 

Access Type: Write access only. Bits (12:4) = 0001. 

All other parameters are omitted in the FOPEN intrinsic call. 

Once the file is opened, the file number (used by other file system intrinsics when referencing this 
file) is returned to the variable LIST. 

The next statement in the program 

IF < THEN FILERROR(LIST,3); 

checks the condition code. If the condition code is CCL, signifying that the FOPEN request was 
denied, the error-check procedure FILERROR is called. 

The FILERROR procedure (see statements 10 through 16 in the program) calls the 
PRINT'FILE'INFO intrinsic, which prints a FILE INFORMATION DISPLAY on the standard list 
device, enabling you to determine the error number returned by FOPEN. 

The QUIT intrinsic call (statement number 15) aborts the process. 
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5C0NTR0L USLINIT 
BEGIN 

BYTE ARRAY DATA1 (0 17) I *"DATAONE"» 

BYTE ARRAY DATA2 (0 «7) » »»DATATW0 "t 

ARRAY LABL(0»8)1*"EMPLOYEE DATA FILE"» 

ARRAY BUFFER <0» 127) I 

INTEGER OFlLEltOFILE2.DUMMY» 

DOUBLE RECI 

INTRINSIC FOPEN.FWRITELABEL.FGETINFO.FREAD.FWRITEDIR.FCLOSE. 
PRINT'FILE'INFO.QUITI 

PROCEDURE FILERROR (FILENO.QUmO) « 
VALUE OUITNOI 
INTEGER FILENO, OUITNOI 
BEGIN 

PRINT'FILE'INFOtFILENO) » 

QUIT(QUITNO) I 
END? 



<<END OF DECLARATIONS» 

DFILEltsFOPEN(DATAl.»5.«100) I 
IF < THEN FILERROR(DFILEl.l) » 

DFILE2txF0PEN(DATA2»*4.«4.128..,l) » 
IF < THEN FILERR0R(DFILE2,2! ; 

FWRITELA8EL(DFILE2»LABLs9»0) I 
IF <> THEN FILERR0R1DFILE2.3) I 

FGETINF0(DFILE1».»»»».«».REC) 1 
IF < THEN FILERR0RCDFILE1.4) I 

INVERT'LOOPi 

DUMMY J=FREAD(DFILE1« BUFFER .128) » 
IF < THEN FILERR0R<DFILE1,5M 
IF > THEN GO END»OF»FILE» 

REC«»REC-1D» 

FWRITEDIR (DFILE2. BUFFER. 128. RECM 

tr <> tucu FILERROR (DFILE2.6) i 

GO INVERT'LOOPI 

END»OF«FILE: 

FCLOSE(DFILEl,4,0n 
IF < THEN FILERRORIDFILE1.8) J 
END. 
*%011» SECONDARY DB STORAGE=*00221 

NO. WARNINGS=000 
0J04I ELAPSED TIME«0 S 00 I 59 



<<OLD FILE-DATAONE>> 
<<CHECK FOR ERROR>> 

<<NEW FILE-DATATWO>> 
<<CHECK FOR ERROR>> 

«FILE ID>> 
<<CHECK FOR ERROR>> 

<<LOCATE EOF>> 
<<CHECK FOR ERROR>> 



«OLD FILE RECORD>> 
<<CHECK FOR ERROR>> 
<<CHECK FOR EOF>> 

<<LAST REDC N0>> 
<<INVERT REC 0RDER>> 
<<CHECK FOR ERR0R>> 

<<C0NTINUE 0PERATION>> 



<<C«tCK FOR tRRGR>> 

<<DELETE OLD FILE>> 
<<CHECK FOR ERROR>> 



Figure 10-10. Closing a New File as a Temporary File 
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CLOSING FILES 

To terminate access to a file, you use the FCLOSE intrinsic. The FCLOSE intrinsic applies to files 
on all devices, and de-allocates the device on which the file resides. If a file was FOPENed 
concurrently several times by the same user, the device is not de-allocated until the last "nested" 
FCLOSE intrinsic is executed. 

The FCLOSE intrinsic may be used to change the disposition of a file. For example, a file opened as 
a new file can be closed and saved as an old file with permanent or temporary disposition. 

When the FOPEN intrinsic opens a file specified as new in the foptions parameter (bits 14 and 
15 = 00), no search of the job temporary or system file domains is conducted to ensure that a file of 
the same' name does not exist already. If such a file is closed and saved with the FCLOSE intrinsic, 
however, a search is conducted. The job temporary file domain is searched if the file is to be saved 
as a temporary job/session file and the system file domain is searched if the file is to be saved as a 
permanent file. If a file of the same name is found in either directory, an error code is returned to 
the calling process. Thus, it is possible to open a new file with the same file name as an existing file, 
but an error will result if an FCLOSE intrinsic attempts to save such a file in the same domain with 
a file of the same name. 

Similarly when the FOPEN intrinsic opens a file specified as old temporary in the foptions 
parameter (bits 14 and 15 = 10), only the job temporary file domain (not the system file domain) is 
searched. If such a file is closed and saved as a permanent file with the FCLOSE intrinsic, the 
system file domain is searched. If a file of the same name is found, an error code is returned to the 
calling process. 

If an FCLOSE intrinsic call is not issued in a program in which files have been opened, MPE closes 
aii files automatically when the program's process terminates. In this case, all opened files are closed 
with the same disposition they had before being opened. New files are deleted, old files are saved 
and assigned to the domain to which they belonged previously - either permanent or temporary. 

CLOSING A NEW FILE AS A TEMPORARY FILE 

Figure 10-10 contains an FCLOSE intrinsic call that closes a new file as a temporary job file. 
The FCLOSE intrinsic call 

FCLOSE(DFILE2,2,0); 
closes the file specified by DFILE2. The parameters specified in the above intrinsic call are 

filenum 



disposition 



Contained in the identifier DFILE2. The file number was assigned to 
DFILE2 when FOPEN opened the file. 

2, for which the bit pattern is as follows: 
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Binary 






























2 




Octal 
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The above bit pattern specifies the following: 

Domain Disposition: Temporary job file (rewound). 

The file is retained in the user's temporary 
(job/session) file domain and can thus be re- 
opened by any process within the job/session. 
The uniqueness of the file name is checked; if 
a file of this name already exists in the job 
temporary file domain, an error code is 
returned. If the file resides on unlabeled mag- 
netic tape, the tape is rewound but not 
unloaded. Bits (13:3) = 010. 

Disc Space Disposition: Unused disc space not returned to the system. 

Bit (12:1) = 0. 

seccode 0, unrestricted access. 

A condition code of CCL is returned if the file is not closed successfully. The statement 

IF < THEN FILERROR(DFILE2,7); 

checks the condition code and, if the condition code is CCL, the error-check procedure FILERROR 
(see statements 13 through 19 in the program) is called. 

The FILERROR procedure calls the PRINT'FILE'INFO intrinsic, which prints a FILE 
INFORMATION DISPLAY on the standard list device, enabling you to determine the error number 
returned to FCLOSE. 

The QUIT intrinsic call 

QUIT(QUITNO); 

aborts the process. 

NOTE 

The QUIT intrinsic causes MPE to close all files with no 
change. Thus, new files are deleted, old files are saved and 
assigned to the same domain to which they belonged 
previously. 

CLOSING A NEW FILE AS A PERMANENT FILE 

Figure 10-11 contains an FCLOSE intrinsic call that closes a new file as a permanent file. 
The FCLOSE intrinsic call 
FCLOSE(OUT,%11,0); 
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SCONTROL USLINIT 
BEGIN 

BYTE ARRAY INPUT (0 » 6) t *»INFILE "I 

BYTE ARRAY DEV ( : 4) »="CARD "» 

BYTE ARRAY OUTPUT ( :7) : ="DATAO*(E "t 

ARRAY BUFFER(0>127) I 

INTEGER IN.OUT.LGTHI 

INTRINSIC FOPEN, FREAD.FWRITE.FCLOSE. PRINT «FILE» INFO, QUIT! 
<< END OF DECLARATIONS >> 



PRIMARY DB STORAGE 
NO, FRRORS*000» 
PROCESSOR TIME=OI0 



IN!*FOPEN(INPUT,%5,»40»DEV> ; 
IF < THEN 
BEGIN 

PRINT'FILE'INFOIINH 
QUIT(l) » 
END» 

0UT:=F0PEN(0UTPUTt*4,%101»128) I 
IF < THEN 
BEGIN 

PRINT'FILEMNFOtOUT) » 
OUIT(2) » 
END! 

COPY'LOOP? 

LGTHIsFREADIIN. BUFFER, 40) j 

IF < THEN 
BEGIN 

PRINT«FILE«INFO(IN) I 
QUITO) « 
END» 
IF > THEN GO ENDtOF'FILEJ 

FWRITE(OUTiBUFFER.LGTH.O) » 
IF <> THEN 
BEGIN 

PRINT»FILE»INFO(OUT) » 
QU1TU) I 
END! 

GO COPY«LOOPJ 

END'OF'FILEI 

a:/-,? ■ F«tosi<owT**il>o*i f :/--4v- 

- IF < THEN 
BESIN . 

<tg*u : T'*-c;X't > : riTMrQ<giiT.!-} 

'.. QUIT <&>»"* 
EM0I 
END. 
:%007l SECONDARY DB STORAGE«»002l3 

NO. WARNINGS=000 
0:03; ELAPSED TIME»0:00I44 



<<CARD READER>> 
<<CHECK FOR ERROR» 

<<PRINT ERROR>> 
<<ABORT>> 



<<NEW DISC FILE>> 
<<CHECK FOR ERROR>> 

<<PRINT ERR0R>> 
<<AB0RT>> 



<<READ A CARD>> 
<<CHECK FOR ERROR>> 

<<PRINT ERROR>> 
<<AB0RT>> 

<<CHECK FOR EOF>> 

<<COPY CARD TO DISC>> 
<<CHECK FOR ERROR>> 

<<PRINT ERROR>> 
<<ABORT>> 



<<CONTINUE COPYING» 



«MAKE PERMANENT** 
<<CHECK FOR ERRQR» 

«?RINT CftROR» 
« ABORT » 



Figure 10-11. Closing a New File as a Permanent File 
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closes the disc file specified by OUT. The parameters specified are 



filenum 



disposition 



Contained in the identifier OUT. The file number was assigned to OUT 
when the FOPEN intrinsic opened the file. 

%11, for which the bit pattern is as follows: 
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Bits 

Binary 

Octal 



seccode 



The above bit pattern specifies the following: 

Domain Disposition: Permanent file. The file is saved in the system 

domain. If the file is a new or old temporary 
file on disc, an entry is created for it in the 
system file directory. (An error code is 
returned if a file of the same name exists 
already in the system directory.) If it is an 
old permanent file on disc, this disposition 
value has no effect. If the file is stored on 
magnetic tape that tape is rewound and un- 
loaded. Bits (13:3) = 001. 

Disc Space Disposition: Unused disc space returned to the system. 

Bits (12:1), (fixed and undefined length 
files only). 

0, unrestricted access. 



A condition code of CCL is returned if the file is not closed successfully. The statement 
IF < THEN 

checks the condition code and, if it is CCL, the next four statements, starting with the BEGIN 
statement, are executed. 

The statement 

PRINT' FILE'INFO(OUT); 

calls the PRINT'FILE'INFO intrinsic, which prints a FILE INFORMATION DISPLAY on the 
standard list device, enabling you to determine the error number returned by FCLOSE. 

The QUIT intrinsic call 

QUIT(5); 
aborts the process. 
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RENAMING A FILE 

You can change the name of an exclusively-opened disc file with the FRENAME intrinsic call. This 
intrinsic effectively changes the actual designator (including lockword, if any) of the file. The file 
must be either: 

1. A new file, or 

2. An existing file to which you have write access. If the file is a permanent file, you must 
be the creator. 

When the FCLOSE intrinsic is called in figure 10-12, a check is made to determine if a file of the 
same name exists and, if one does exist, the FRENAME intrinsic is used to rename the file being 
closed. 

The statement 

FCLOSE(DFILE2,1,0); 

attempts to close the file specified by DFILE2 as a permanent file. The file specified by the file 
number contained in DFILE2 is "DATATWO", which was opened as an old temporary file. If the 
file is closed successfully, a CCE condition code is returned and program control is transferred to 
statement label DONE, terminating program execution. If CCE is not returned, the FCHECK 
intrinsic is called to determine the error number. The statement 

IF ERROR=100 THEN 

checks whether the error number is 100 (duplicate file name in the system file directory). Note that 
even though the file DATATWO was opened successfully from the job temporary file directory, it is 
possible that some other user already has a permanent file named DATATWO in the system file 
directory, hence an error to this effect will be returned when the program attempts to close a job 
temporary file as a permanent file. 

The statement 

FREN AME(DFILE2, ALTNAME) ; 

attempts to rename the file to the actual designator (ALTDATA) contained in the byte array 
ALTNAME. The second FCLOSE call then attempts to close the file under this new name. 

If the second FCLOSE call fails, the PRINT'FILETNFO intrinsic causes a FILE INFORMATION 

t-* t ^t-.t ii7 j i _ •— j.-j iL» „^„„ ,1„,.^1 Uo+ AaxAna Tn arMifinn t.hp st.at.pmfint 

JJi.Srij.tt. I lO DC prulLCU UI1 uic suaiiu.cu.vA iwn ""i^-v. --** ««»• — —— , 

FWRITE(LIST,MESSAGE,19,0); 

prints the message 

DUPLICATE FILE NAME - FIX DURING BREAK 

i j,u„ r< a TTairmjir att ^nt^i-icio fall fsnisps a session break. 

MPE prompts with a colon on the terminal and now you can enter MPE commands. 
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00001000 00000 
00002000 00000 
00003000 00000 1 
0000*000 00005 1 
00005000 00006 1 
00006000 00005 1 
00007000 00005 1 
00008000 00023 1 
00009000 00023 1 
00010000 00023 1 
00011000 00023 1 
00012000 00023 1 
00013000 00023 1 
00014000 00023 1 
00015000 00000 1 
00016000 00000 1 
00017000 00000 1 
00018000 00000 2 
00019000 00002 2 
00020000 00004 2 
00021000 00000 1 
00022000 00000 1 
00023000 00000 1 
00024000 00000 1 
00025000 00011 1 
00026000 00015 X 
00027000 00015 1 
00028000 00025 1 
00029000 00031 1 
00030000 00031 1 
00031000 00037 1 
00032000 00043 1 
00033000 00050 1 
00034000 00054 1 
00035000 00054 1 
00036000 00054 1 
00037000 00061 1 
00038000 00065 1 
00039000 00066 1 
00040000 00066 1 
00041000 00072 1 
00042000 00075 1 
00043000 00101 1 
00044000 00101 1 
00045000 00106 1 
00046000 00112 1 
00047000 00112 1 
00048000 00117 1 
00049000 00117 1 
00050O00 00117 1 
00051000 00123 1 
00052000 00124 1 
00053000 00131 1 
00054000 00134 1 
00055000 00134 2 
00056000 00137 2 
00057000 00137 2 
00058000 00143 2 
00059000 00144 2 
00060000 00146 2 
00061000 00153 2 
00062000 00154 2 
00063000 00155 2 
00064000 00155 1 
PRIMARY DB STORAGES 
NO, FRRORS«OOOI 
PROCFSSOR TIMEsOlOO 



SCONTROl USLINIT 
BEGIN 

BYTE ARRAY DATA2 (0 ! 7) : *"DATATWO '»? 

BYTE ARRAY LISTFlLE (0 18) t *»LISTFILE "I 

BYTE ARRAY ALTNAME ( I 7) :="ALTDATA •'» 

ARRAY BUFFER(0:127) I 

ARRAY MESSAGE(0U8) J*»DUPLICATE FILE NAME - FIX DURING BREAK"! 

INTEGER DFILE2,LIST,ERR0RI 

DOUBLE RECt»ODI 

INTRINSIC EOPEN.FREADLABEL.FREADOIR.FWRITE.FCLOSE.FRENAME, 
FREADSEEK,CAUSEBREAK.FCHECK,PRINT'FILE«INFO»QUIT» 

PROCEDURE FILERROR(FILENO,QUIT*JO> I 
VALUE QUITNOI 
INTEGER FILENO.QUITNOt 
BEGIN 

PRINT'FILE«INFO(QUITNO) t 

OUIT(OUITNO) J 
END I 



<<END OF DECLARATIONS>> 

DFILE2l=F0PEN(DATA2,S6,*4,12B>» 
IF < THEN FILERR0R(DFILE2,1!I 

LIST!=F0PEN(LISTFILE,*14.%1) I 
IF < THEN FILERR0R(LIST.2) • 

FREADLABEL ( DF I LF2. BUFFER. 1-28.0) » 
IF <> THEN FILERR0R(DFILE?.3> I 
FWRITE<LIST. BUFFER. 9,0) I 
IF <> THEN FILERR0R(LIST,4) I 

LIST«L00P! 

FREADDIR (DFILE2, BUFFER, 128, REC) I 
IF < THEN FILERR0R(DFILE2,5) I 
IF > THEN GO END»OF»FILEI 

RECl*REC*2DI 

FREADSEEK(DFILE2,REC) I 

IF < THEN FILERR0R(DFILE2,S) I 

FWRITFILIST, BUFFER, 35,0) » 
IF <> THEN FILERR0R(LIST,7) * 

GO LIST'LOOPI 

END»OF«FILF! 

IF s THEN GO DONE I 



ClOSF ! 



- tf ■'->_ OF . F2.ALTI J-. I 



IF * THF& GO DONF.I 

!»«**? »FtUE«I«t"><PFH,£2M 
F¥»UF«LJ5r»«:*SAH>t**0M 
CAUSFftPEAKH 
GO CLOSE* 
END» 
DONE t END. 
K012* SECONDARY DB STORAGE=»00240 

NO. WARNINGS*000 
1041 ELAPSED TIME»0»00I58 



<<OLD TEMP FILE>> 
<<CHECK FOR ERROR>> 

<<$STDLIST>> 
<<CHECK FOR ERROR>> 

<<FILE ID>> 
<<CHECK FOR ERROR>> 
<<OISPLAY ID>> 
<<CHECK FOR ERROR>> 



<<EVERY OTHER R£CD>> 
<<CHECK FOR ERROR>> 
<<CHECK FOR EOF>> 

<<EVERY OTHER RECD>> 
<<FILL SYSTEM BUFFER>> 
<<CHECK FOR ERROR>> 

<<ALTERNATE RECORDS>> 
<<CHECK FOR ERROR>> 

<<CONTINUE LISTING>> 



<<DIIPIICATF FILE NAM E >> 

«CHA»ise fil£ nmf» 

<<TRY AGAIN>> 

<«><JOQ Fti5*:*%> 
<«!»HJNT L«Rj>H-> 
«&£CK MEl.P» 

<<LOOP zacm*> 



Figure 10-12. FRENAME Intrinsic Example 
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NOTE 

The : RENAME command can be used to rename a file. 
However, this command cannot be used to rename a file that 
is currently open in a program. For example, if a file of the 
alternate name (ALTDATA) also exists in the system file 
directory, the : RENAME command must be used to rename 
this file instead of the file opened by the program. Thus, a 
: RENAME command of the form 

: RENAME ALTDATA, ALT AAA A/TEMP 

(attempting to rename the opened temporary file 
ALTDATA) will result in the error message 

EXCLUSIVE VIOLATION: FILE ACCESSED EXCLUSIVELY (FSERR 91) 

The -.RENAME command must be used to rename the old, 
unopened file in the system directory, as follows: 

:RENAME ALTDATA,ALTAAAA 
See the MPE Commands Reference Manual for a further discussion of the : RENAME command. 
Once : RESUME is typed to resume program execution, the statement 

GO CLOSE; 
transfers program control back to the label CLOSE and the FCLOSE sequence is tried again. 

WRITING A FILE SYSTEM ERROR-CHECK PROCEDURE 

As you noticed in some of the examples, the statements 

BEGIN 

PRINT'FILETNFO(fitenum); 

QUIT(num); 

END; 

. . . i-. -r . -i *• __j_* j_i_.:_ a A j-U-s-^'i-iJTf'U /Mit <i nvnrtrom iwi+.H 

were repeated after each intrinsic can. instead 01 repeating una tuuc """"S"""" " *~~&— - 

multiple intrinsic calls, however, it is more efficient (because less code is generated) to write an 
error-check procedure and merely call this procedure where necessary in a program. 

Figure 1U-13 contains a program wmcn mciuueo on cnui-uici,n p^y,*,****.*-, 

calls this procedure if an error occurs. The program opens a card reader and a disc file, reads the 
card file, writes these records into the disc file, then closes the disc file. 

The error check procedure (statements 10 through 17 in figure 10-13) contains two parameters: 
FILENO (integer) and QUITNO (integer by value). FILENO is an identifier through which is passed 
the file number. This file number is used by PRINT'FILETNFO to print a FILE INFORMATION 
DISPLAY for that file. 

The QUIT intrinsic aborts tne program s process anu prints uie ^umw ^ ^- "* ■»" 

message, enabling you to determine the point at which the process was aborted. 



10-45 



PAGE nOOl HEWLETT-PACKARD 32100A.05.1 SPL/3000 TJE, OCT 7, 1975. 10:31 AM 



OO001OO0 
00002000 
00003000 
00004000 
00005000 
00006000 
00007000 

oooosooo 

00009000 

00010000 

00011000 

00012000 

00013000 

00014000 

00015000 

00016000 

00017000 

00018000 

00019000 

00020000 

00021000 

00022000 

00023000 

00024000 

00025000 

00026000 

00027000 

00028000 

00029000 

00030000 

00031000 

00032000 

00033000 

00034000 

00035000 

00036000 

00037000 

00038000 

00039000 

00040000 



00000 
00000 
00000 1 
00005 1 

00004 1 

00005 1 
00005 1 
00005 1 
00005 1 
00005 1 
00005 1 
00000 1 
00000 1 
00000 1 
00000 2 
00002 2 
00004 2 
00000 1 
00000 1 
00000 1 
00000 1 
00012 1 
00016 1 
00016 1 
00027 1 
00033 1 
00033 1 
00033 1 
00041 1 

00045 1 

00046 1 
00046 1 
00053 1 
00057 1 
OO057 1 
00062 1 
00062 1 
00062 1 
00066 1 
00072 1 

PRIMARY DB STORAGE 
NO. ERRORS»000| 
PROCFSSOR TIME=OIOO 



SCONTROl USLINIT 

BEGIN 

BYTE ARRAY INPUT ( :6> »="INFI(_E »» 
BYTE ARRAY DEV (0 14) !*»CARD "I 
BYTE ARRAY OUTPUT (0 t 7) !="DATAOME "» 
ARRAY BUFFER(0U27) » 
INTEGER IN.OUT.LGTH; 



INTRINSIC FOPEN.FREAD.FWRITE.FCLOSE. PRINT tFILE' INFO, QUITI 

pftooLDtf»E f itf-mm i*-rixvo» at/ma* * 

VALUE SVI7N0J 

JUMP'S! FILFNQ.aUITNG* 



Pfi IU* » F fU?,» 1*8-0 (FKJEsfoji I 
QUIT CHUT NO I | 
END* 

<< END OF DECLARATIONS >> 

INI=FOPEN(INPUT.*5,.40«DEV) I 
IF < THEN FILERROR(IN.l) I 

OUT:=FOPEN(OUTPUT.»4.»101,128) I 
IF < THEN FILERR0RJ0UT.2) I 

COPY»LOOP: 

LGTH«»FREAD(IN.BUFFER,40)J 
IF < THEN FILERRORUN.3) | 
IF > THEN GO END'OF'FILEl 

FWRITEtOUT. BUFFER. LGTH. 0)| 
IF <> THEN FILERROR(OUT,4) J 



GO COPY<LOOP| 

END'OF'FILE: 

FCLOSE(OUT.«ll,0) I 

IF < THEN FILERR0RI0UT.5) I 

END. 

*007l SECONDARY DB STORAGE**00213 
NO. WARNINGSsOOO 

!03» ELAPSED TIME=0I00!31 



<<CARD READER>> 
<<CHECK FOR ERROR>> 

<<NEH DISC FILE>> 
<<CHECK FOR ERROR>> 



<<READ A CARD» 
<<CHECK FOR ERROR>> 
<<CHECK FOR EOF» 

<<COPY CARD TO OISC>> 
<<CHECK FOR ERROR>> 

<<CONTINUE COPYING» 



<<MAKE PERMANENT>> 
<<CHECK FOR ERROR>> 



Figure 10-13. Error-Check Procedure Example 
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READING A FILE IN SEQUENTIAL ORDER 

To read records, or portions of records, from a file in sequential order, you use the FREAD 



intrinsic. 



When the FREAD intrinsic executes, a logical record pointer advances to the next record. Then, the 
next time the FREAD intrinsic is called, the next record is read. Even if a portion of a record is 
read, a subsequent FREAD ignores the unread portion of the last record (because the logical record 
pointer has advanced) and begins reading the next record. 

NOTE 

The logical record pointer is a number kept by MPE to 
indicate the next sequential record to be accessed in a file. 

If RIO access is used, FREAD will input the next active record, automatically ignoring de-activated 
records. The fact that inactive records may have been ignored is transparent to the caller. 

If an RIO file is accessed using the non-RIO method, FREAD will input from the next block. 
The program shown in figure 10-14 reads a card file. The FREAD statement 
LGTH:=FREAD(IN,BUFFER,40); 

reads a record from the card reader file designated by the variable IN (the file number was assigned 
to IN when the FOPEN intrinsic opened the file) and transfers this record to the array BUFFER in 
the stack. The statement reads up to 40 words from the record, then returns a positive value to 
LGTH which indicates the actual length of the information transferred. 

If an error occurs during execution of the FREAD intrinsic, a condition code of CCL is returned. 
The statement 

IF < THEN 

checks the condition code and, if the condition code is CCL, the next four statements are executed. 
The PRINT'FILETNFO intrinsic call causes a FILE INFORMATION DISPLAY to be printed on 
the output device so that you can determine the error number returned by FREAD, and the QUIT 
intrinsic aborts the process. 

When the end-of-file is encountered on the card file, a condition code of CCG is returned. The 
statement 

IF > THEN GO END'OF'FILE; 

checks for this condition code and, when it occurs, transfers program control to the label 
END'OF'FILE. If the end-of-file condition is not encountered, the FWRITE statement is executed 
and the 

GO COPY'LOOP; 

statement transfers program control back to the beginning of the copy loop. The FREAD intrinsic 
is called again and the next record is read. 

The FREAD intrinsic operates in the usual manner to read foreign discs. However, IBM diskettes 
number sectors starting with one rather than zero, and the diskette driver adds one to all sector 
addresses for IBM diskettes. Therefore, you specify record number zero to read sector number one 
on an IBM diskette. 
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5CONTR0L USLINIT 
BEGIN 

BYTE ARRAY INPUT (0 16) I *"INFILE "I 

BYTE ARRAY DEV (0 14) J"»CARD "» 

BYTE ARRAY OUTPUT ( » 7) I =»OATAOME "J 

ARRAY BUFFER10U27) I 

INTEGER IN.OUT.LGTHt 

INTRINSIC FOPEN, FREAD.FWRITE.FCLOSE. PRINT »FILE» INFO, QUITJ 
<< END OF DECLARATIONS >> 



INJ«FOPEN(INPUT,*5.«40»DEV> I 
IF < THEN 
BEGIN 

PRINT»FILE«INFO(IN)l 
QUIT (1)1 
END I 

OUTl*F0PEN(OUTPUT»«4,%101,128> i 
IF < THEN 
BEGIN 

PRINTiFILE'INFO(OUT) I 
QUIT(2) I 
END! 

COPYiLOOPJ 

LGTMI*FREAO IN. BUFFER, 411 I 

If < THEN 

P*INT«| ILE'tNFO 1NH 

IF - THFN 50 ENOi >F»FILEI 
'-»=>-'*- ■ T. JUFFER.LGTH.t ,; 



PRINT. FILE«INFO<C Tl i 

mm 

GO COPYiLOOPJ 

END'OF'FILE: 

FCLOSE(OUT»»ll,0) I 
IF < THEN 
BEGIN 

PRINT'FILE»INFO(OUT) I 
QUITI5M 
END! 
END. 
=*007l SECONDARY DB STORAGE**0021 3 

NO. WARNINGSsOOO 
0:03l ELAPSED TIME=O:00J44 



<<CARO READER>> 
<<CHECK FOR ERROR» 

<<PRINT ERROR>> 
<<AB0RT>> 



<<NEW DISC FILE>> 
«CHECK FOR ERROR» 

<<PRINT ERROR>> 
<<ABORT>> 



<<ABORT>> 

««chsc* res £or» 



«PRINT E.Bpn*» 
«ABORT» 



<<CONTINUE COPYING>> 



<<MAKE PERMANENT>> 
<<CHECK FOR ERROR>> 

<<PRINT ERROR>> 
<<ABORT>> 



Figure 10-14. FREAD and FWRITE Intrinsics Example 
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WRITING RECORDS INTO A FILE IN A SEQUENTIAL ORDER 

To write records, or portions of records, from your buffer to a file in sequential order, you use the 
FWRITE intrinsic. 

When the FWRITE intrinsic executes, the logical record pointer advances to the next record. Then, 
the next time the FWRITE intrinsic is called, information is written into the next record position. 
When information is written to a file composed of fixed-length records (and buffering is not 
specified in the FOPEN call), the file system pads all short records with binary zeros for a binary 
file, or ASCII blanks for an ASCII file to bring the records up to the fixed length required. If nobuff 
was specified in FOPEN, automatic buffering is not provided by MPE. 

The FWRITE statement in figure 10-14. 

FWRITE(OUT,BUFFER,LGTH,0); 

writes a record from the array BUFFER into the disc file designated by the variable OUT. (The file 
number was assigned to OUT when FOPEN opened the file.) The length of the record is specified 
by LGTH. (LGTH was assigned its value when FREAD read the record and transferred it to 
BUFFER, so in this case the same number of words being read from the card reader are being 
written to the disc.) 

The control parameter is specified as to indicate that no carriage control code is included in the 
record. (Carriage control, of course, is not necessary for a disc file but the parameter is included 
because all FWRITE parameters are required.) 

A condition code of CCE signifies that the FWRITE request was granted. The statement 

IF <> THEN 

checks for a "not equal" condition code and, if CCG or CCL is returned, the next four statements 
are executed. The PRINT'FILETNFO intrinsic causes a FILE INFORMATION DISPLAY to be 
printed on the output device, enabling you to determine the error number returned by FWRITE. 
The QUIT intrinsic aborts the process. 

If CCE is returned, the next four statements are not executed, the GO COPY 'LOOP statement is 
executed, and the FREAD and FWRITE intrinsic calls are repeated until FREAD detects the end of 



The FWRITE intrinsic operates in the usual manner to write to foreign discs. However, IBM 
diskettes number sectors starting with one rather than zero, and the diskette driver adds one to all 
sector addresses for IBM diskettes. Therefore, you specify record number zero to write to sector 
number one on an IBM diskette. 



READING A FILE IN DIRECT-ACCESS MODE 

As you recall from the discussion of the FREAD intrinsic, a record read with that intrinsic is 
determined by the position of the logical record pointer. Each successive FREAD then reads the 
next record in sequence because the logical record pointer advances one record each time FREAD is 
executed. It is possible, however, to access specific records in a disc file with the FREADDIR 



10-49 



intrinsic. The record number to be read is specified as one of the parameters in the FREADDIR 
intrinsic call. Note that the FREADDIR intrinsic call may be issued only for a disc file composed of 
fixed-length or undefined-length records. 

The FREADDIR intrinsic operates in the usual manner to read foreign discs. However, IBM 
diskettes number sectors starting with one rather than zero, and the diskette driver adds one to all 
sector addresses for IBM diskettes. Therefore, you specify record number zero to read sector 
number one on an IBM diskette. 

Figure 10-15 contains a program that reads every other record in a disc file using the FREADDIR 
intrinsic. The FREADDIR intrinsic call 

FREADDIR(DFILE2,BUFFER,128,REC); 

reads a record from the file designated by DFILE2 (the file number was assigned to DFILE2 when 
the FOPEN intrinsic opened the file) and transfers this record to the array BUFFER in the stack. 
Up to 128 words are read from the record. The parameter REC specifies which record is read. The 
double integer value 0D (double integers are indicated by the suffix D in SPL) was assigned to REC 
(see statement number 9 in the program), and so the first time the LIST'LOOP is executed, the first 
record in the file (logical record number 0) is read. REC is incremented by 2D each time the loop is 
executed, therefore, physical record number 3 (logical record number 2) is read the second time the 
loop is executed, then 5, 7, etc. The logical record pointer is advanced by one each time the 
FREADDIR intrinsic is executed. Since the record number to be read is specified by REC, however, 
the FREADDIR intrinsic does not necessarily read records in sequential order, as does the FREAD 
intrinsic. 

If the information is not read successfully by a FREADDIR intrinsic call, a CCL condition code is 
returned. The statement 

IF < THEN FILERROR(DFILE2,3); 

checks the condition code and, if it is CCL, calls the error-check procedure FILERROR. The 
FILERROR procedure prints a FILE INFORMATION DISPLAY on the standard list device, 
enabling you to determine the error number returned by FREADDIR, then aborts the program's 
process. 

A condition code of CCG signifies an end-of-file condition and the statement 

IF > THEN GO END'OF'FILE; 
transfers program control to the label END'OF'FILE when the end-of-file condition is encountered. 
OPTIMIZING DIRECT-ACCESS FILE READING 

If you know in advance that a certain record is to be read from a file with the FREADDIR intrinsic, 
you can speed up the I/O process by issuing a FREADSEEK intrinsic call. 

The FREADSEEK intrinsic moves the record from the file to a file system buffer. Then, when the 
FREADDIR intrinsic call is issued, the record is transferred from this buffer to the buffer in the 
stack specified by FREADDIR. The I/O process is enhanced when FREADSEEK is used, if the 
record to be read can be brought into the buffer before the FREADDIR call is issued. An FREAD- 
SEEK call should not immediately be followed by the FREADDIR call; enough time must be 
allowed for the I/O process to bring in the record from the file. 
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The LIST 'LOOP in figure 10-15 performs the following functions: 

1. Issues a FREADDIR intrinsic call to transfer a record (specified by REC) from a file 
(specified by DFILE2) to an array (BUFFER) in the stack. 

2. Increments REC by 2D. 

3. Issues an FREADSEEK intrinsic call to read the record specified by the new value of REC 
and to transfer this record to a system buffer. 

4. Lists the record in the stack array (BUFFER) on the standard list device. 

5. Repeats the loop. 

The next time LIST'LOOP is executed, the FREADDIR intrinsic reads the record from the file 
system buffer to the stack array (BUFFER), eliminating the need to wait for file access and thus 
reducing the execution time of the loop. 

Note: Can also be used with FPOINT and FREAD. 

To write information into a specific record in a disc file, you can use the FWRITEDIR intrinsic. 

Unlike the FWRITE intrinsic, which writes records into a file depending on the position of the 
logical record pointer, the FWRITEDIR intrinsic can write into any record of a file by specifying 
the logical record number as a parameter (or physical record number if in NOBUF access mode). 

The FWRITEDIR intrinsic call may be issued only for disc files of fixed-length or undefined-length 
records. 

The FWRITEDIR intrinsic operates in the usual manner to write to foreign discs. However, IBM 
diskettes number sectors starting with one rather than zero, and the driver adds one to all sector 
addresses for the IBM diskettes. Therefore, you specify record number zero to write to sector 
number one on an IBM diskette. 

Figure 10-16 contains a program that reads records from one file and writes these records, in inverse 
order, into a second me using uits r wmunjui mumou,. 

The FGETINFO intrinsic (see page 10-68) is used to locate the end-of-file in the file to be read. 
This information is returned to the variable REC. 

The FREAD statement 

DUMMY:=FREAD(DFILE1,BUFFER,128); 

reads up to 128 words from the first record of the file DATAONE (specified by the file number 
assigned to DFILE1 by the FOPEN intrinsic when the file was opened) and transfers this 
information to the array BUFFER. 
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00112 1 
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00117 1 
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00124 1 
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00134 1 
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00137 
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SCONTROL USLINIT 
BEGIN 

BYTE ARRAY 0ATA2 (0 1 7) I*"DATATWO »! 

BYTE ARRAY LISTFILE (0 I 8) : =»LISTFILE "I 

BYTE ARRAY ALTNAME ( 1 7) t =»ALTD4TA "I 

ARRAY BUFFER(0:127) I 

ARRAY MESSAGE(0U6) :»"DUPLICATE FILE NAME 

INTEGER DFILE2. LIST, ERROR! 

DOUBLE REClaOD! 



FIX DURING BREAK"! 



INTRINSIC FOPEN,FREADLABEL,FREADDIR,FWRITE,FCLOSE,FRENAME, 
FREADSEEK,CAUSEBREAK,FCHECK, PRINT "FILE 'INFO, QUIT I 



PROCEDURE FILERROR(FILENO,QUITNO) I 
VALUE OUITNO! 
INTEGER FILENO.QUITNOI 
BEGIN 

PRINT«FILE»INFO(QUITNO) J 
QUIT(OUITNO) I 
END I 

<<END OF DECLARATIONS^ 

DFILE2!=F0PEN(DATA2,»6,*4,128) I 
IF < THEN FILERR0R(DFILE2,1) I 

LISTJ=F0PEN(LISTFILE,»14,*1)» 
IF < THEN FILERR0R(LIST,2),I 

FREADLABELIDFILF2, BUFFER, 128,0)1 
IF <> THEN FILERROR(DFILE?»3)« 
FWRITE(LIST, BUFFER, 9,0) I 
IF <> THEN FILERR0R(LIST,4) I 

LIST»LOOP! 

FRtAr>rWR(OFILF«>,BUFfetf.l2fl,Rrc>» 

IT < $H£U Ht£fiW)IK&Fia£,f»ti 
If •* THtn W Fie»«OF»FIi£* 

RECS=REC*2DI 

if * T«e* 1 f*].imm9im-iL£z**>it 

FWRITFILIST, BUFFER, 35, 0) ! 
IF <> THEN FILERR0R(LIST,7) I 

GO LIST«LOOPl 

END»OF»FILES 

FCLOSEIDFILE2, 1,0)1 
IF = THEN GO DONE! 
FCHECM0FILE2, ERROR) I 
IF ERROR=100 THEN 
BEGIN 

FRENAME(DFILE2, ALTNAME) I 
CLOSE! 

FCLOSE(DFILE2,l,0M 

IF » THEN GO DONE! 

PRINT 'FILE* INFO (DFILE2) I 

FWRITE(LIST,MESSAGE,19,0)I 

CAUSEBREAK! 

GO CLOSE! 
END! 
DONE! END, 
5S012! SECONDARY DB STORAGE=*00240 

NO. WARNINGS»000 
1041 ELAPSED TIME»0!00!58 



<<OLD TEMP FILE>> 
<<CHECK FOR ERROR>> 

<<SSTDLIST>> 
<<CHECK FOR ERROR>> 

<<FILE ID>> 
<<CHECK FOR ERROR>> 
<<DISPLAY ID>> 
<<CHECK FOR ERROR>> 



*«-«£<!* Ffs« £««roft>» 
<-<l**£CK FOR t(JF>» 

<<EVERY OTHER RECD>> 

<*;CMECK FOR tRROR» 

<<ALTERNATE RECORDS>> 
<<CHECK FOR ERROR>> 

<<CONTINUE LISTING>> 



<<MAKE PERMANENT>> 
<<LISTING DONE>> 
<<FCLOSE ERROR>> 
<<DUPLICATE FILE NAMf>> 

<<CHANGE FILE NAME>> 

<<TRY AGAIN>> 
<<GOOD FCLOSE>> 
<<PRINT ERROR>> 
<<SEEK HELP>> 
<<SESSION BREAK>> 
<<LOOP BACK>> 
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Figure 10-15. FREADDIR and FREADSEEK Intrinsics Example 
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SCONTROL USLINIT 

BEGIN 

BYTE ARRAY DATA1 (0 I 7H ""DATAONE "J 
BYTE ARRAY DATA2 (0 I 7) »*"DATATW0 "« 
ARRAY LABU0I8) l»"EMPLOYEE DATA FILE'M 
ARRAY BUFFERI0O27) I 
INTEGER 0FILE1.DFILE2. DUMMY! 
DOUBLE RECI 

INTRINSIC FOPEN.FWRITELABEL.FGETINFO.FREAD 
PRINT'FILE'INFO.QUIT! 

PROCEDURE FILERROR(FILENO.QUITMO) 1 
VALUE OUITNOI 
INTEGER FILENO.QUITNOI 
BEGIN 

PRINT»FILE«INFO(FILENOM 

QUIT(QUITNO) I 
ENDI 



.FWRITEDIR.FCLOSE. 



107 1 
116 1 
116 1 
116 1 
122 1 
126 1 
126 1 
132 1 
136 1 
STORAGE 
000! 
IME*0I0 



<<END OF OECLARATIONS» 

DFILElt»FOPEN(DATAl,*5i*100) « 
IF < THEN FILERROR(DFILEl.l) » 

0FILE2i*F0PEN<DATA2»«4.S4.128.,,l>! 
IF < THEN FILERROR(DFILE2,2)» 

FWRITELABEL(DFILE2.LABLt9,0)l 
IF <> THEN FILERR0R«DFILE2?3! I 

FGETINFOlDFILElf, ,»»•»♦ »»RECM 
IF < THEN FILERR0R(DFILE1,4)1 

INVERT'LOOPJ 

DUMMY I =FREAD(DFILE1 .BUFFER. 128) ! 
IF < THEN FILERROR(DFILE1.5>» 
IF > THEN GO END'OF'FILEJ 

RJFCt»REC-lPt 
FwftITE0IR(DFILE2tBUFFER.129.REC)» 

GO INVERT'LOOPI 

END'OF'FILE! 

FCLOSEIDFILE2, 2.0)1 

IF < THEN FILERROR(DFILE2.7)t 

FCLOSE(DFILE1,4,0)I 

IF < THEN FILERROR(DFILE1.8) » 

END. 
*%011l SECONDARY DB STORAGE=»*00221 

NO. WARNINGSsOOO 
0104J ELAPSED TIME«0«00!59 



<<OLD FILE-DATAONE>> 
<<CHECK FOR ERROR>> 

<<NEW FILE-DATATWO>> 
<<CHECK FOR ERROR>> 

<<FILE ID>> 
<<CHECK FOR ERROR>> 

<<LOCATE EOF>> 
<<CHECK FOR ERROR>> 



<<OLD FILE RECORD>> 
<<CHECK FOR ERROR>> 
<<CHECK FOR EOF>> 

«last m&c »<o>> 

-U INVERT ?FC 0«0£»» 
<<CONTINUE OPERATION>> 



<<SAVE NEW AS TEMP>> 
<<CHECK FOR ERROR>> 

<<DELETE OLD FILE>> 
<<CHECK FOR ERROR>> 



Figure 10-16. FWRITEDIR Intrinsic Example 
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The statement 

REC:=REC-1D; 

decrements REC by the double integer value ID to arrive at the logical record number of the last 
record in the file. (REC contains a current value of last physical record (last logical record + ID) as 
a result of the FGETINFO intrinsic call.) 

The FWRITEDIR statement 

FWRITEDIR(DFILE2,BUFFER,128,REC); 

writes the record contained in the array BUFFER to the file specified by DFILE2. The parameters 
specified in the FWRITEDIR intrinsic call are 

f ilenum Contained in DFILE2, which was assigned the file number of the file 

DATATWO when the FOPEN intrinsic opened the file. 

tar £ et BUFFER, the array that contains the record to be written. 

tcount 128 words 

recnum REC, which contains the logical record number of the last record in the 

file. 

If the FWRITEDIR request is successful, a CCE condition code is returned. The statement 
IF <> THEN FILERROR(DFILE2,6); 

checks for a "not equal" condition code and, if such a condition code is returned, the error-check 
procedure FILERROR is called. 

The FILERROR procedure prints a FILE INFORMATION DISPLAY on the standard list device, 
enabling you to determine the error number returned by FWRITEDIR, then aborts the program's 
process. 

If a condition code of CCE is returned, the 

IF <> THEN FILERROR(DFILE2,6); 
statement is not executed and the 

GO INVERT'LOOP; 

statement transfers program control to the statement label INVERT'LOOP, causing the invert loop 
to be repeated. 

The second time the loop is executed, the FREAD intrinsic reads the second record from 
DATAONE and the FWRITE intrinsic writes this record into the next-to-last record in DATATWO 
(REC has been decremented again by ID). The loop repeats until the last record is read from 
DATAONE. 
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LOCKING AND UNLOCKING FILES 

Occasionally, for example, when a file is opened so that records can be changed, it is advantageous 
to dynamically lock the file to signal that another user should not attempt to change the same 
record at the same time. This is accomplished with the FLOCK intrinsic; a locked file is unlocked 
with the FUNLOCK intrinsic. 

When an FOPEN intrinsic specifying the dynamic locking aoption is issued against a disc file, a 
Resource Identification Number (RIN) is established for that file. (The MPE RIN mechanism pro- 
vides a waiting queue facility). A user's process then can call intrinsics that dynamically lock and 
unlock the file by alternately acquiring and releasing exclusive use of this RIN. 

It is important to note that the FLOCK and FUNLOCK intrinsics only provide a means of signaling 
that the caller wants temporary exclusive use of the file. All processes must cooperate by using the 
same signaling system to ensure data integrity. If one process fails to call FLOCK or does so im- 
properly, the data may be corrupted and unexpected results may occur. FLOCK locks as RIN, not 
the file itself. 

Because the RIN's used in dynamic file locking are available system wide, the user employing the 
file-locking intrinsics must follow the rules governing global RIN's (see Section VI). Specific capa- 
bility-class rules governing file locking are: 

1. Standard Capabilities. A user's running process (program) can lock only one file at a time. 

2. Process-Handling Optional Capability. Within the job process structure, only one file can 
be locked at any one time. 

3. Multiple RIN Optional Capability. No restrictions are imposed. 

Figure 10-17 contains a program that updates the file DATAONE. The FLOCK intrinsic call 

FLOCK(DFILEl,l); 
locks the file. The parameters specified in the intrinsic call are 

.£-•7 /~1 4- «:_„,] ™ T*T?TT "C 1 ! ■.-.r'U-Irt'U •mne, t. fini mi r\A +-l"»rt ■Filo MlimKoT ^"P 

/ llttrtUffl \j\JUKt<\lllCKA ill J-/J-' lUiJl, Willis Al WOO aooign^u uixt; i"t- nwmw^i vj. 

DATAONE when the FOPEN intrinsic opened the file. 

lockcond 1, which specifies that the file is to be locked unconditionally. This 

means that if the file cannot be locked immediately, the caiiing process 
is suspended until the file can be locked. 

A condition code of CCL is returned if the FLOCK request was not granted. The statement 

IF < THEN FILERROR(DFILEl,4); 

checks for a condition code of CCL and, if it is returned, the error-check procedure FILERROR is 

n t mi nTrnnnrtn -J.*--,. ^~J - 4. - - TTtTTTi TXTT1AT11U 1 H1TAXT T-fcTOT>T A \T 4-1 n 4-«-» ~1 A «*J 

cauea. rne r iLiHittrt^tt procedure prints a rijjui iiNrwiuv±.rt.j.±vvi>i morufii uu me oloiiuoiu 
output device, enabling you to determine the error number returned by FLOCK, then aborts the 
program's process. 
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SCONTROL USLINIT 
BEGIN 

BYTE ARRAY DATA1 (0 i 7) 1 ="DATAONE "« 

ARRAY RUFFER<01127> I 

INTEGER DFILE1.LGTH,DUMMY,IN,LISTI 

INTRINSIC FOPEN.FRE AD. FUPDATE, FLOCK, FUNLOCK.FCLOSE, 
PRINT'FILE'INFO.QUIT.FWRITE.FREADJ 

PROCEDURE FILERROR (FILENO.OUITNO) » 
VALUE QUITNOI 
INTEGER FILENO, QUITNOI 
BEGIN 

PRINT'FILE'INFOIFILENO) I 

QUIT(QUITNO) I 
END! 

<<END OF DECLARATIONS>> 



PRIMARY DR STORAGF 
NO. FRRORS=000j 
PROCFSSOR TIMF=o:o 



DFILE1 S=FOPEN( DATA i,%5»*34 5» 123) I 
IF < THEN FILERRORIDFILEl.lM 

lNi=FOPEN(,»244) J 

IF < THEN FILERROR(IN,2M 

LISTi=F0PEN(,S614.«l> I 

IF < THEN FILERROR(LIST.3) \ 

UPDATE'LOOP! 

LGTH:=FREAD(DFILE1. BUFFER, 128) » 
IF < THFN FILERR0R<DFILE1,5) 1 
IF > THEN GO ENO'OF'FILEI 

FWRITE(LIST.BUFFER.-20,%320) J 
IF <> THEN FILERR0R(LIST,6) I 

DUMMYl=FREAD(IN,BUFFER(30) .5) I 
IF < THEN FILERR0R(IN,7) I 
IF > THEN GO END'OF'FILEJ 

FUPDATEtDFILEl. BUFFER. 128) I 
IF <> THEN FILERR0RIDFILE1.8) I 

M'NLOCK(r>ILfll I 

... ". •- <■ . Rl -,.-.;.. .,,,, 

GO UPDATE'LOOPI 

END'OF'FILE! 

UNLOCK «s? I LUS* 

if ,* utftt FILERROR<DFH.El*lfl)t 

FCLOSE(OFILtl.O.O) I 
IF < THEN FILERR0R<DFILE1,11> I 
END. 
=*007l SECONDARY DB STORAGE=»00204 

NO. WARNINGS=000 
0I03J ELAPSED TIME=0:00!17 



<<OLD DISC FILE>> 
<<CHECK FOR ERROR>> 

<<SSTDIN>> 

<<CHECK FOR ERROR>> 

<<SSTDLIST>> 
<<CHECK FOR ERROR>> 



<<: ock Fii.E/siispeNo-»> 

<<GET EMPLOYEE RECD>> 
<<CHECK FOR FRROP>> 
<<CHECK FOR EOF>> 

<<EMPLOYEE NAME>> 
<<CHECK FOR ERR0R>> 

<<EMPLOYFF NUMBER>> 
<<CHECK FOR ERROR>> 



<<EMPLOYFE RECORD>> 
<<CHECK FOR ERROR>> 

«ALLW other ACCESS» 
«CHiC!t ?£>H FRROR>> 

<<C0NTINUE UPDATE>> 



<* ALLOW f'THEw %5ttf5V> 
<cChhCK fOft F RS0H>> 

<<DISP-NO CHANGF>> 
<<CHECK FOR ERROR>> 



Figure 10-17. FLOCK and FUNLOCK Intrinsics Example 
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The statements below perform the following: 



LGTHJ=FREAD<DFILE1, BUFFER, 128) » 
IF < THFN FILERR0R(DFILE1,5H 
IF > THEN SO END'OF'FILE! 

FWRITEI LIST, BUFFER ,-20 »*320> I 
IF <> THEN FILERRORILIST.fiM 

DUMMYI*FREAO(IN,HUFFER(30) ,5) » 
IF < THEN FILERR0R(IN,7U 
IF > THEN GO END'OF'FILE! 

FUPOATE(DFILEl. BUFFER, 128) i 
IF <> THEN FILERR0R(DFILE1,8> ; 



<<GET EMPLOYEE RECD>> 
<<CHECK FOR FRROR>> 
<<CHECK FOR EOF>> 

<<EMPLOYEE NAME>> 
<<CHECK FOR ERROR>> 

<<EMPL0YFE NUMBER>> 
<<CHECK FOR ERROR>> 



<<EMPLOYEE RECORD>> 
<<CHECK FOR ERROR>> 



1. Read a record from the file DATAONE. 

2. Print 20 bytes of this record (employee name) on the standard list device (a terminal in 
this case; the program was run interactively). 

3. Read an employee number from the terminal into the array BUFFER starting at word 30. 

4. Update the record by writing the information contained in BUFFER, including the 
employee number, into file DATAONE. 

The statement 

FUNLOCK(DFILEl); 

unlocks the file DATAONE (the file number of which is specified by DFILE1), thus allowing other 
users to access the file. Note that this statement follows each update in UPDATE'LOOP and is 
repeated in END'OF'FILE to insure that the file is unlocked in case an end-of-file condition causes 
a branch out of UPDATE'LOOP before the file is unlocked. 

UPDATING A FILE 

To update a logical record of a disc file, you use the FUPDATE intrinsic. 

The FUPDATE intrinsic affects the last logical record (or block for NOBUF files) accessed by any 
intrinsic call for the file named, and writes information from a buffer in the stack into this record. 
Note that the record number need not be supplied in the FUPDATE intrinsic call; FUPDATE 
automatically updates the last record referenced in any intrinsic call. 

The file containing the record to be updated must have been opened with the update aoption 
specified in the FOPEN call and must not contain variable-length records. 

FUPDATE operates in the usual manner to update a foreign disc file. 

■c:~..-«« 1 n 1 Q rtrtwfpme o rM-r^m-cn-t-* fhaf nnonc an r\lr1 rHcr* filp nr\r\ nr*rlnt.ps rprrirHs in t.hp flip TVlP 

I?it£U±C J.V-H-> V/UllbaUia t* ^IV^LUU UiiWV V^^V^AAU Mii wxu ^A*k/<^ j.**>~ *-.**» w~j^^a»^^» -. ~— «- ~- ~ — 

update information (employee number) is entered from a terminal (the program was run 
interactively) into a buffer in the stack, then the contents of the buffer are used to update the 
record. 
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SCONTROL USLINIT 
BEGIN 

BYTE ARRAY DATA1 (0 : 7) 1 ="DATAONE "I 

ARRAY RUFFER<0!127> I 

INTEGER DFILE1.LGTH,DUMMY.IN,LISTI 

INTRINSIC FOPEN.FREAO.FUPOATE» FLOCK, FUNLOCK.FCLOSE. 
PRINT • FILE "INFO, QUIT •FWRITE.FRE AD; 

PROCEDURE FILERROR(FILENO.QUITMO) J 
VALUE QUITNOI 
INTEGER FILENO, QUITNOI 
BEGIN 

PRINT»FILE»INFO(FILENO) » 

QUIT(QUITNO) I 
END I 



<<END OF DECLARATIONS>> 

0FILEl:=F0PEN(0ATAl,%5.»345,128) I 
IF < THEN FILERRORtDFILEI.ii 5 

IN:=F0PEN(,»244) » 

IF < THEN FILERR0RIIN.2) I 

LISTl=F0PEN(,»614.*l) I 

IF < THEN FILERRORILIST.3) I 

UPDATE'LOOP: 

FLOCK(OFILEI.I) 1 

IF < THEN FILFRRORIDFILE1.41 I 

LGTHl=FREA0<DFILEl»BUFFER,128> I 
IF < THFN FILERR0R(0FILE1,5) I 
IF > THEN GO END'OFiFILEl 

FWRITF(LIST.BUFFER,-20.*320! » 
IF <> THEN FILERR0R!LIST,6) I 

DIIMMY:=FREAO(IN,HUFFER(30) .5) 1 
IF < THFN FILERROR(IN,7) I 
IF > THEN GO END'OF'FUEl 

FllRlrATf fUflLU ,RHF*F.JJ, l?m | 

FUNLOCK(DFILEl) I 

IF <> THEN FILERR0R(DFILE1#9! I 

GO UPDATE'LOOP! 

END'OF'FILE! 

FUNLOCK(DFILEl) I 

IF <> THEN FILERROR(DFILEl.lO) » 

FCLOSEIDFILfc.1,0,0) I 
IF < THEN FILERRORtDFILEI.ii)! 
END. 
»*007l SECONDARY DB STORAGE=%00 204 

NO. WARNINGS=000 
0103! ELAPSED T IME=0 1 00 : 17 



<<OLD DISC FILE>> 
<<CHECK FOR FRROR>> 

<<*STDIN>> 

<<CHECK FOR ERROR>> 

<<$STDLIST>> 
<<CHECK FOR ERROR>> 



<<LOCK FILE/SUSPEND>> 
<<CHECK FOR ERROR>> 

<<GFT EMPLOYEE RECD>> 
<<CHECK FOR FRROR>> 
<<CHECK FOR EOF>> 

<<EMPLOYEE NAME>> 
<<CHECK FOR ERROR>> 

<<EMPLOYFF NUMBER>> 
<<CHECK FOR FRROR>> 



«C«FCK *W ER««V,Jc*> 

<<ALLOW OTHER ACCESS>> 
<<CHECK FOR ERROR>> 

<<CONTINUE UPDATE>> 



<<ALLOW OTHER ACCESS>> 
<<CHECK FOR ERROR>> 

<<DISP-NO CHANGF>> 
<<CHECK FOR ERROR>> 



Figure 10-18. FUPDATE Intrinsic Example 
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The statement 

LGTH:=FREAD(DFILE1,BUFFER,128); 
reads an employee record from the file specified by DFILE1 into the array BUFFER in the stack. 

The statement 

FWRITE(LIST,BUFFER,-20,%320); 

then displays this record on the terminal ($STDLIST has been opened with the FOPEN intrinsic 
and the resulting file number was assigned to LIST). 

The statement 

DUMMY:=FREAD(IN,BUFFER(30),5); 

reads an employee number, entered on the terminal ($STDIN has been opened with the FOPEN 
intrinsic and the resulting file number was assigned to IN), into the array BUFFER starting at word 30. 

The statement 

FUPDATE(DFILE1,BUFFER,128); 

then calls the FUPDATE intrinsic to update the last record accessed in the file specified by 
DFILE1. The contents of BUFFER (including the employee number entered from the terminal) are 
written into this record. Up to 128 words are written. 

If the FUPDATE request was granted, a CCE condition code results. The statement 
IF < > THEN FILERROR(DFILEl,9); 

checks for a "not equal" condition code and, if such is the case, calls the error-check procedure 
FILERROR. The procedure FILERROR prints a FILE INFORMATION DISPLAY on the terminal, 
enabling you to determine the error number returned by FUPDATE, then aborts the program's 
calling process. 

USING THE IOWAIT INTRINSIC 

Figure 10-19 shows a program that opens several terminals for input. 

The statement 

OUT: =FOPEN(OUTPUT,4,l „DE V) ; 

opens the line printer for output and the WHILE statement begins a loop to open the terminals. 

In order to open a file with both the NOBUF and NO-WAIT aoptions specified, the program must 
be running in privileged mode, and this program is switched to privileged mode with the statement 

GETPRIVMODE; 
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SCONTPOL USLINIT 
BEGIN 

BYTE ARRAY OUTPUTCO «6) t«"OUTPUT "| 

BYTE ARRAY TNAMCO 16) S="DATAIN "| 

BYTE ARRAY DEVCOl 7) |s"LP TERM »> 

INTEGER OUT, FILE, LGTH,Ii«-1,PR0MPT|b»T ",DONEl=0l 

EQUATE MAXTRMs3> 

ARRAY BUFP(0J36«MAXTRM) j 

INTEGER ARRAY OPENCO! MAXTPM) | 

DEFINE CCL ■ IF < THEN QUIT*, 
CCG » IF > THEN QUIT*, 
CCNE* IF <> THEN QUIT* I 

INTRINSIC FOPEN,FREAD,FWPlTE,FCLOSE,GETPRIVMODE,GETUSERMODE, 
IOWAIT,QUIT> 



<<END OF DECLARATIONS» 

OUT j«FQPE*f OUTPUT, 4, i,,^**! CCfcm* 
SSG-IN 

CC.hO)t 

OWS»U)J*FH.tj 

tOWA«{FItE)» CC»BC6>I 

END» 
WAIT! 



«CHECK FOR EBROR» 

4€SkW file ximmm» 
■ '-. ■- - ,- -=-,, 

«COMPf.ET« REQUFST» 



FILE:sIOWAITCO,,LGTH)> CCLC8)) 
IF > THEN 
BEGIN 

FCL05E(FILE,0,0)J CCL(9)J 
IFCDONEf«DONE+l)>aMAXTRM THEN GO EXITi 
END 
ELSE 
BEGIN 
l:=-l> 

DO Ijel+l 

UNTIL OPENCDaFILE OP IsMAXTPMj 
IF IsMAXTRM THEN QUITUOj 

FWPITECOUT,BUFR(I»36J,-LGTH,0) r 
CCNEC11)! 

FWRITE (FILE, PROMPT, 1,%320) I CCNEC12)! 
IOWAITCFILE)! CCNEC13)> 

FREAD(FILE,BUFR(I»36),-72)| CCNE(14)i 
END J 
GO TO WAITJ 
EXITIEND, 
%013| SECONDARY DB STORAGE-%00175 

NO, WARNINGScOOO 
102) ELAPSED TIM£a0l0OiO8 



«WAIT FOR 1ST D0NE» 
«E0F ON TERM READ» 

«TERMINAL FILE» 
«ALL TERMS CLOSED?» 



«SET BUFFER INDEX>> 
«INCR BUFFER INDEX» 
«SEARCH FOR FILE NO» 
<<FILE NOT F0UND» 
«COPY INPUT TO LP>> 
«CHECK FOR ERROR» 
«OUTPUT ? PROMPT>> 
«COMPLETE REQUEST» 
«INPUT DATA-NOWAIT>> 

«C0NTINUE» 



Figure 10-19. Using the IOWAIT Intrinsic 
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The statement 

FILE:=FOPEN(TNAM,%405,%4404,36,DEV(3)); 
opens a terminal. The parameters specified are 

formaldesignator DATAIN, which is contained in the byte array TNAM. 

foptions %405, for which the bit pattern is 
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aoptions 



The above bit pattern specifies the following file options: 

Domain: Old permanent file, system file domain. Bits (14:2) = 01. 

ASCII/Binary: ASCII. Bit (13:1) = 1. 

File Designator: Actual file designator = formal file designator. Bits 

(10:3) = 000. 
Record Format: Fixed-length records. Bits (8:2) = 00. 
Carriage Control: Carriage-control character expected. Bit (7:1) = 1. 

%4404, for which the bit pattern is as follows: 
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The above bit pattern specifies the following access options: 

Access Type: Input/output. Bits (12:4) = 0100. 

Multirecord: Non-multirecord. Bit (11:1) = 0. 

Dynamic Locking: Disallowed. Bit (10:1) = 0. 

t?„„i, ,„;„«. p^ni,i<.i<m o-.™ci! riofanif wViati T /O anffiss is snecified and 

bits (8:2) = 00. 
Inhibit Buffering: Selected (NOBUF). Bit (7:1) = 1. 
No-Wait I/O. Selected. Bit (4:1) = 1. 

recsize 36 words. 

device T (terminal), specified in element (3) of byte array DEV. 

Once the file is opened, the program is switched back to the non-privileged mode with the statement 

GETUSERMODE; 
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The first file number is saved in FILEBASE, a prompt is displayed on the terminal, and the IOWAIT 
intrinsic is called to wait until the request is completed. Input from the terminal is read and stored 
in BUFR at the location determined by the file number. (Input from the first terminal opened starts 
at BUFR location 0, the next input starts at location 36, and so forth.) 

The statements 

FILE : = IOWAIT(0 , , LGTH) , 
IF > THEN 

wait for an end-of-file indication (the user enters an :EOF: command) from the first terminal on 
which the input is complete. If the end-of-file indication is received, this terminal is closed. 

The input from the terminal is printed on the line printer and another prompt is displayed. Again, 
the IOWAIT intrinsic is called to wait until the request is completed. When DONE = MAXTRM (all 
terminals closed), control is passed to EXIT and the program terminates. 

Note that the IODONTWAIT intrinsic (not shown in figure 10-21) behaves the same as IOWAIT 
with one exception: if IOWAIT is called and no I/O has completed, the calling process is suspended 
until some I/O completes; if IODONTWAIT is called and no I/O has completed, control is returned 
to the calling process. Thus, the program shown in figure 10-21 would not have suspended if the 
IODONTWAIT intrinsic had been called, and control would have returned to the program. 

WRITING AND READING USER FILE LABELS 

MPE allows you to write and read user-defined labels with the FWRITELABEL and FREADLABEL 
intrinsics. Such labels are very useful, for example, labels can be used on files that are updated fre- 
quently in order to determine the time of the last update. User-defined labels can be read from and 
written to either disc files or labeled magnetic tape files. The tape files must be previously labeled 
with an ANSI-standard or IBM-standard label. (See Page 10-80 for a discussion of labeled magnetic 
tape files.) 

WRITING A USER FILE LABEL ON A DISC FILE 

When a disc file is created, MPE automatically supplies a file label in the first sector of the first 
extent occupied by that file. User-supplied labels are located in the sectors immediately following 
the MPE file label. The number of records allowed for user-supplied labels for any file must be 
specified in the userlabels parameter of the FOPEN intrinsic call that creates the file. 

In figure 10-20 the FOPEN intrinsic call 

DFILE2:=FOPEN(DATA2,%4,%4,128,„l); 

opens a new file and specifies 1 for the userlabels parameter (last parameter before parenthesis in 
this example), meaning that one 128-word record will be set aside for user labels. Any attempt to 
write a label beyond this 128-word limit will result in a CCG condition code and the intrinsic 
request will be denied. Note that any subsequent FWRITELABEL intrinsic calls will write over an 
existing label. 
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j.iic otaucinciiu 

FWRITELABEL(DFILE2,LABL,9,0); 

calls the intrinsic FWRITELABEL to write a user-supplied label. The parameters specified in the 
intrinsic call are 

filenum Supplied by DFILE2, which was assigned the file number when the 

FOPEN intrinsic opened the file. 

target The array LABL, containing the string "EMPLOYEE DATA FILE", 

which will be written as the user file label. 

tcount 9 words, specifying the length of the string to be transferred from the 

array LABL. 

labelid 0, specifying the number of the label. (0 = first label, 1 = second label, 

etc.). 

If the label is written successfully, a CCE condition code results. The statement 

IF <> THEN FILERROR(DFILE2,3); 

checks for a "not equal" condition code and, if such is the case, calls the error-check procedure 
FILERROR. The FILERROR procedure prints a FILE INFORMATION DISPLAY on the standard 
list device, enabling you to determine the error number returned by FWRITELABEL, then aborts 
the program's process. 

READING A USER FILE LABEL ON A DISC FILE 

To read a user file label, you use the FREAD LABEL intrinsic. Before reading occurs, MPE checks 
to ensure that you have read-access capability for the file on which the file label is to be read. The 
file therefore must be opened with one of the following access type aoptions: 

Read access only. Bits (12:4) = 0000. 
Input/output access. Bit (12:4) = 0100. 
Update access. Bits (12:4) = 0101. 

In figure 10-21, the FOPEN intrinsic call 

DFILE2:=FOPEN(DATA2,%6,%4,128); 
contains the aoptions parameter %4, which specifies input/output access. 
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SCONTROL USLINIT 
BEGIN 

BYTE ARRAY DATA1 (0 » 7) I -"DATAONE "I 

BYTE ARRAY DATA2 <0 I 7) » -"DATATWO "I 

ARRAY LABLI0I8) »-"EMPLOYEE DATA FILE"! 

ARRAY BUFFER(0I127)I 

INTEGER 0FILE1.DFILE2. DUMMY! 

DOUBLE REC» 

INTRINSIC FOPEN.FWRITELABEL.FGETINFO.FREAD.FWRITEDIR.FCLOSE. 
PRINT'FILE'INFO.QUITI 

PROCEDURE FILERROR(FILENO.QUmO) I 
VALUE QUITNOI 
INTEGER FILENO. QUITNOI 
BEGIN 

PRINT'FILE'INFOfFILENO! ! 

QUIT(QUITNO) I 
END I 



<<END OF DECLARATIONS>> 

DFILEltsFOPEN(DATAl.%5.*100M 
IF < THEN FILERROR(DFILElti>» 

DFILE2I*F0PEN(DATA2.*4»*4.128.,»1) I 
IF < THEN FILERR0R1DFILE2,2)I 

fWTEL«m *t«lf £*U«i t^SH 

if <> tmkn furmmmrtLi^iii 

FGETINFOIDFILE1..........RECM 

IF < THEN FILERR0R(DFILE1,4)I 

INVERT'LOOPl 

DUMMY I »FREA0(DFILE1. BUFFER. 128) » 
IF < THEN FILERR0R(DFILE1,5)» 
IF > THEN GO END'OF'FILEI 

RECI»REC-1DI 

FWRITEDIR (DFILE2. BUFFER. 128. REC) I 

IF <> THEN FILERR0R(DFILE2.6) I 

GO INVERT'LOOPl 

ENDtOF'FILEl 

FCLOSE(DFILE2,2,0)I 

IF < THEN FILERROR1DFILE2.7M 

FCLOSE(DFILE1,4,0) I 

IF < THEN FILERR0R(DFILE1.8)I 

END. 

%011< SECONDARY D8 STORAGE»*00221 
NO. WARNINGSsOOO 

1041 ELAPSED TIME-0J00I59 



<<OLD FILE-DATAONE>> 
<<CHECK FOR ERROR>> 

<<NEW FILE-DATATWO>> 
<<CHECK FOR ERROR>> 

«CHec*t *m mm*?**- ■ 

<<LOCATE EOF>> 
<<CHECK FOR ERROR>> 



«OLD FILE RECORD» 
<<CHECK FOR ERROR>> 
<<CHECK FOR EOF>> 

<<LAST REDC NO>> 
<<INVERT REC OROER» 
<<CHECK FOR ERROR>> 

«CONTINUE OPERATION>> 



<<SAVE NEW AS TEMP>> 
<<CHECK FOR ERROR>> 

<<DELETE OLD FILE>> 
<<CHECK FOR ERROR>> 



Figure 10-20. FWRITELABEL Intrinsic Example (Disc File) 
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SCONTROL USLINIT 
BEGIN 

BYTE ARRAY DATA2 ( ! 7) J»"DATATWO •'! 

BYTE ARRAY LISTFILE {OJ 8) I =»LISTFILE "! 

BYTE ARRAY ALTNAME ( I 7) I=»ALTDATA »! 

ARRAY BUFFER (OS 1275 ! 

ARRAY MESSAGE (01 18) »*"DUPLICATE FILE NAME 

INTEGER DFILE2.LIST. ERROR! 

DOUBLE REC»*0D! 



FIX DURING BREAK'S 



INTRINSIC FOPEN.FREADLABEL.FREADDIR.FWRITE.FCLOSE.FRENAME. 
FRE ADSEEK,CAUSEBREAK.FCHECK,PRI NT 'FILE 'INFO. QUIT » 

PROCEDURE FILERROR(FILENO.QUIT»JO> I 
VALUE QUITNO! 
INTEGER FILENO. QUITNO! 
BEGIN 

PRINT»FILE«INFO(QUITNO> I 

QUIT(QUITNO) I 
END! 



155 1 

STORAGE 

000! 

IMEaOiO 



<<END OF DECLARATIONS>> 

DFILE2S=F0PEN(DATA2.»6»«4.128) » 
IF < THEN FILERR0R(0FILE2,1) ! 

LIST«=F0PEN(LISTFILE»*14.*1) ! 
IF < THEN FILERRORILIST.2) I 

FUEAPi »HFl(DFI! F2,f>UFFtPi!28f 0) I 
--.-... ILFRPO« '- .F ■• " • 

F WRITE '<"[' 1ST , BUFFER' .9,0)1 

IF <> THEN FILERR0R(LIST,4) I 

LISTiLOOP: 

FREADDIR (DFI LE2, BUFFER. 128.REC! I 
IF < THEN FILERROR(DFILE2.5) ! 
IF > THEN GO END»OF"FILE! 

REC?=REC»2D! 

FREADSEEK (DFILE2.REC) ! 

IF < THEN FILERR0RIDFILE2.6) ! 

FHRITFILIST.BUFFER.35.0) J 
IF <> THEN FILERR0R(LIST,7) ! 

GO LIST«LOOP! 

END'OF'FILF! 

FCLOSE(DFILE2,1,0) I 
IF = THEN GO DONE! 
FCHECK (DFILE2. ERROR) ! 
IF ERROR=100 THEN 
BEGIN 

ppCMAutr inr ILE2:ALTNAME ) ! 
CLOSE: 

FCLOSEIDFILE2.1.0) ! 
IF * THEN GO DONE! 
PRINT«FILE'INF0(DFILE2) I 
FWRITE(LIST,MESSAGE.19.0) I 
CAUSEBREAKI 
GO CLOSE! 
END! 
DONEtEND. 
s«012l SECONDARY DB STORAGE=%00240 
NO. WARNINGS»000 

l ■ ci »»ern TTyr. a • n n • c o 



<<OLD TEMP FILE>> 
<<CHECK FOR ERROR>> 

<<$STDLIST>> 
<<CHECK FOR ERROR>> 

•KFJiF ""5>> 

-'. ■ - •■ - ' 
<<DISPLAY ID>> 
<<CHECK FOR ERROR>> 



<<EVERY OTHER RECD>> 
<<CHECK FOR ERROR>> 
<<CHECK FOR EOF>> 

<<EVERY OTHER RECD>> 
<<FILL SYSTEM BUFFER>> 
<<CHECK FOR ERROR>> 

<<ALTERNATE RECORDS>> 
<<CHECK FOR ERROR>> 

<<CONTINUE LISTING>> 



<<MAKE PERMANENT>> 
<<LISTING DONE>> 
<<FCLOSE ERROR>> 
<<DUPLICATE FILE NAME>> 

<<CH.4NGE FILE NAME>> 

<<TRY AGAIN>> 
<<GOOD FCLOSE>> 
<<PRINT ERROR>> 
<<SEEK HELP>> 
<<SESSION BREAK>> 
<<LOOP BACK>> 



Figure 10-21. FREADLABEL Intrinsic Example (Disc File) 
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The statement 

FREADLABEL(DFILE2,BUFFER,128,0); 

reads a user file label from the file specified by DFILE2. The parameters specified in the intrinsic 
call are 

filenum Supplied by DFILE2, which was assigned the file number when the 

FOPEN intrinsic opened the file. 

target BUFFER, the array in the stack to which the file label is transferred. 

tcount 128, specifying the maximum number of words to be transferred. 

labelid 0, specifying the number of the label to be read. 

If the label is read, a CCE condition code results. The statement 
IF <> THEN FILERROR(DFILE2,3); 

checks for a "not equal" condition code and, if such is the case, calls the error-check procedure 
FILERROR. The FILERROR procedure prints a FILE INFORMATION DISPLAY on the standard 
list device, enabling you to determine the error number returned by FREADLABEL, then aborts 
the program's process. 

OBTAINING FILE ACCESS INFORMATION 

You can request access and status information about an open file with the FGETINFO or the 
FFILEINFO intrinsics. FFILEINFO is a superset of FGETINFO and is designed to replace it. 
However, programs may use either intrinsic exclusively or in conjunction with one another. 

USING FGETINFO 

The program shown in figure 10-22 uses the FGETINFO intrinsic call to locate the end-of-file, 
as follows: 

FGETINFO(DFILEl„„„„„REC); 

All parameters of the FGETINFO intrinsic except filenum, which supplies the file number of the 
file for which information is to be obtained, are optional. Note that all parameters in the above 
intrinsic call except filenum and eof are omitted. The commas between DFILE1 and REC signify to 
MPE that the parameters are omitted. Omissions from the end of the parameter list need not be 
signified to MPE by commas; instead, the parenthesis after REC signifies that this is the last 
parameter in the intrinsic call. 

If the blksize parameter is specified, the value returned will depend on the access mode, RIO or 
non-RIO. Blksize reflects only the size of the data area within the block when RIO access is used. In 
this case, the blocking factor can be computed in the usual way, block-size divided by record-size. 

When the files are accessed using the non-RIO method, the blksize parameter will reflect the actual 
size of the block, including the Active Record Table area used to implement the RIO access 
method. This value can be used to determine the size of the data transfer, especially for file 
replication. 
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SCONTROL USLINIT 
BEGIN 

BYTE ARRAY DATA1 (0 I 7) 1«»DATA0NE "I 

BYTE ARRAY DATA2 (0 «7> :»»DATATW0 "I 

ARRAY LABLf0«8)l="EMPLOYEE DATA FILE'M 

ARRAY BUFFER<0»127) I 

INTEGER DFILE1.DFILE2.DUMMYI 

DOUBLE RECI 

INTRINSIC FOPEN.FWRITELABEL.FGETINFO.FREAD.FWRITEDIR.FCLOSE. 
PRINT'FILE'INFO.QUITI 

PROCEDURE FILERROR (FILENO.QUITNO) t 
VALUE QUITNOI 
INTEGER FILENO.QUITNOJ 
BEGIN 

PRINTiFILE'INFO(FILENO) I 

QUIT(QUITNO) I 
END! 



«END OF DECLARATIONS>> 

DFILE1:*FOPEN(DATA1.*5«%100) » 
IF < THEN FILERROR(DFILEl.l) » 

DFILE2J*F0PEN(DATA2.%4»*4»128.,,1) » 
IF < THEN FILERR0R(DFILE2,2>» 

FWRITELABELIDFILE2.LABL.9»0) I 
IF <> THEN FILERR0R<DFILE2»3M 

FGETINFO(OFILEl..f»..»».RSCM 
IF < THEN FILER»0R(0F1LE1,4)» 

INVERT'LOOPl 

DUMMY! =FREAD (DFILE1 .BUFFER. 128) » 
IF < THEN FILERR0R(DFILE1.5) * 
IF > THEN GO END'OF'FILEI 

REC«=REC-1D« 

FWRITEDIR (DFILE2. BUFFER. 128. REC) I 

IF <> THEN FILERROR(DFILE2»6) I 

GO INVERT'LOOPI 

END>OF»FILE» 

FCLOSE(DFILE2,2.0!I 

tc < THEN F!LERROR(DFILE?.7) I 

FCL0SE<DFILE1,4,0H 
IF < THEN FILERROR(DFILEI.B) I 
END. 
i«0UI SECONDARY DB STORAGE»*00221 

NO. WARNINGSsOOO 
0J04I ELAPSED TIME*0:00:59 



<<OLD FILE-DATAONE>> 
<<CHECK FOR ERROR>> 

<<NEW FILE-DATATWO>> 
<<CHECK FOR ERROR>> 

«FILE ID>> 
<<CHECK FOR ERROR>> 

<<LOCATE EOF>> 



<<OLD FILE RECORD>> 
<<CHECK FOR ERROR>> 
<<CHECK FOR EOF>> 

<<LAST REDC NO>> 
<<INVERT REC ORDER>> 
<<CHECK FOR ERROR>> 

<<CONTINUE OPERATION>> 



<<SAVE NEW AS TEMP>> 
<<CHECK FOR ERROR>> 

<<DELETE OLD FILE>> 
<<CHECK FOR ERROR>> 



Figure 10-22. FGETINFO Intrinsic Example 
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The size of a block can be computed by: 



B = 



128 



■I\ 



F*R+A, 



_F 
16 



(A notation in the form Fxl means "ceiling (x)" — the smallest integer greater than or equal to x. 
See p. 3-3). Where B = block-size (in sectors), F = blocking-factor, R = record-size (in words), and A 
= size of the Active Record Table (in words). 

The blocking factor can be recomputed by: 



F= 16*B*128 | 
I 16*B+1 I 



(A notation in the form Lx J means "floor (x)" — the largest integer less than or equal to x). 

Thus, the data-block size can be computed as F*R. Note that double-integer arithmetic is necessary 
for the above calculation since B*128 < = 32767 (thus 16 * B * 128 < = 524272). 

The recpt parameter will always return the ordinal of the next actual record, whether it is active or 
inactive. 

A double integer value equal to the number of logical records currently in the file is returned to 
REC. 

If the FGETINFO request is not granted, a CCL condition code is returned. The statement 
IF < THEN FILERROR(DFILEl,4); 

checks for a condition code of CCL and, if such is the case, calls the error-check procedure 
FILERROR. This procedure prints a FILE INFORMATION DISPLAY on the standard list device, 
enabling you to determine the error number returned by FGETINFO, then aborts the program's 
process. 

USING FFILEINFO 

Although itemvalue is declared as a byte array, the data type of the value returned depends on the 
item itself. Some languages, SPL/3000 and Cobol II for example, permit you to pass any data type 
structure to a formal byte array parameter. This means you do not have to equivalence the data 
structures or to move the data from a temporary buffer to the desired variable. For this reason, the 
following example would retrieve the filename, foptions, and record pointer. SPL automatically 
converts the word addresses for foptions and recptr to byte addresses. 

byte array FNAME (0:27); 

integer FOPTIONS; 

double RECPTR; 

FFILEINFO(FILENUM, 2, FOPTIONS, 9, RECPTR, 1, FNAME); 

OBTAINING FILE-ERROR INFORMATION 

When a file system intrinsic returns a condition code indicating that an error occurred, you can 
request more details about the error in order to correct it. The FCHECK intrinsic call is used for 
this purpose. 
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In Figure 10-23, the FCHECK intrinsic is used to determine the error number if a condition coae 
error is returned when the FCLOSE intrinsic is executed. The statement 
FCHECK(DFILE2,ERROR) ; 

specifies that error information is to be returned for the file number designated by DFILE2. The 
error number is returned to ERROR as a 16-bit code. The statement 

IFERROR=100THEN 
checks the error number returned and, if ERROR =100, executes a file rename procedure. 

USING FERRMSG 

This intrinsic is called usually following a call to FCHECK. The error code returned in the call to 
FCHECK can then be used as a parameter in the call to FERRMSG. 

For example, suppose a CCL condition is returned by a call to FCLOSE, a call to FCHECK requests 
the particular error code, then a call to FERRMSG can be used to retrieve a printable message 
associated with the code. 

FCLOSE(FILNUM,1,0); 

IF< 

THEN BEGIN 

FCHECK(FILNUM,ERRNUM); 

FERRMSG(ERRNUM,MESSAGE,LENGTH); 

PRINT(MESSAGE,-LENGTH,0) ; 
END 
TERMINATE; 

The message printed explains the FCHECK code. If the FCHECK code has no assigned meaning, the 
following message is returned: 

UNDEFINED ERROR errorcode 

MAGNETIC TAPE CONSIDERATIONS 

Every standard reel of magnetic tape designed for digital computer use has two reflective markers 
located on the back side of the tape (opposite the recording surface). One of these marks is located 
behind the tape leader at the beginning of tape (BOT) position, and the other is located in front of 

j-u„ j- 4-« n ;i nv «4- 4-U^ sonA ^-F fono fliYYT^ nrwci+irm 

Lilt: uapc lj.cu.icx at mc y?ij.u ^j. uwyv v^"-' * / ^wui^w". 

These markers are sensed by the tape drive itself and their position on the tape (left or right side) 
determines whether they indicate the start or end of tape positions. (See below.) 

MAGNETIC 
TAPE 




„ _„ T ,-.. . , .... _. , . TDAII CD 

LEADER BU l riLC srHoc t»j i ih™i_i_h 

As far as the magnetic tape hardware and software are concerned, the BOT marker is much more 
significant than the EOT marker because BOT signals the start of recorded information, but EOT 
simply indicates that the remaining tape supply is running low and the program writing the tape 
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SCONTROl USLINIT 
BEGIN 

BYTE ARRAY DATA2 (0 I 7) :»"DATATW0 "1 

BYTE ARRAY |_ ISTFILE (0 I 8) i =»LISTFILE "I 

BYTE ARRAY ALTNAME (0 » 7) »='<ALTDATA "I 

ARRAY BUFFER(0:127)I 

ARRAY MESSAGE10U8) !=»DUPLICATE FILE NAME 

INTEGER DFILE2,LIST,ERR0RI 

DOUBLE RECl»ODI 



FIX DURING BREAK"I 



INTRINSIC FOPEN,FREADLABEL»FREADDIR,FWRITE.FCLOSE,FRENAME, 
FREADSEEK,CAUSEBREAK,FCHECK,PRINT«FILE»INFO,QUITl 

PROCEDURE FlLERROR<FILENO,QUIT>JO> I 
VALUE QUITNOI 
INTEGER FILENO, QUITNOI 
BEGIN 

PRINT'FILE'INFO(QUITNO) I 

QUIT(OUITNO) I 
FNDl 



PRIMARY DB STORAGE 
NO. FRRORSrOOOl 
PROCFSSOR TIMEsQlO 



<<END OF DECLARATIONS^ 

DFILE2S=F0PEN<DATA2,*6,*4,128) I 
IF < THEN FILERR0R(DFILE2,1) I 

LISTI=F0PEN(LISTFILE.»14,»1) I 
IF < THEN FILERR0RILIST.2) » 

FREADLAREHDFILF2, BUFFER, 128,0) I 
IF <> THEN FILERR0RIDFILE2.3) I 
FWRITEILIST, BUFFER, 9,0) I 
IF <> THEN FILERR0R(LIST,4) I 

LISTiLOOP: 

FREADDIR(DFILE2, BUFFER, 1 28, REC) I 
IF < THEN FILERR0R(DFRE2,5) I 
IF > THEN GO END'OFiFILEI 

REC:=REC*2DI 

FREADSEEK(DFILE2,REC) I 

IF < THEN FILERR0R<DFILE2,S) I 

FWRITF (LIST, BUFFER, 35,0) I 
IF <> THEN FILERR0R(LIST,7) » 

GO LIST'LOOPI 

END'OF'FILF: 

FCLOSE<r>FILE2,l,0> I 
IF a THFN GO DONEI 
FCHECK{DFILE2. ERROR) » 
IF ERROR*! 00 -THEN 
BEGIN 

FRENAME (DFILE2, ALTNAME) I 
CLOSE! 

FCLOSE(DFILE2, 1,0)1 
IF * THEN GO DONEI 
PRINT«FILF»INF0(DFILE2) I 
FWRITEfLIST. MESSAGE, 19,0) I 
CAUSEBREAKI 
GO CLOSEI 
END! 
DONEIEND. 
=%012l SECONDARY DB STORAGE=»00240 

NO. NARNINGS=000 
01041 ELAPSED TIME*0!00!58 



<<OLD TEMP FILE>> 
<<CHECK FOR ERROR>> 

<<$STDLIST>> 
<<CHECK FOR FRROR>> 

<<FILE ID>> 
<<CHECK FOR ERROR>> 
<<DISPLAY ID>> 
<<CHECK FOR ERROR>> 



<<EVERY OTHER RECD>> 
<<CHECK FOR ERROR>> 
<<CHECK FOR EOF>> 

<<EVERY OTHER RECD>> 
<<FILL SYSTFM BUFFER>> 
<<CHECK FOR ERROR>> 

<<ALTERNATF RECORDS>> 
<<CHECK FOR FRROR>> 

<<CONTINUE LISTING>> 



<<MAKE PERMANENT>> 
<<LISTING DONE>> 
« F CLOSE ERROR >> 
«DWLICATE FILE NAWF>> 

<<CHANGE FILE NAME>> 

<<TRY AGAIN>> 
<<GOOD FCLOSE>> 
<<PRINT ERROR>> 
<<SEEK HELP>> 
<<SESSION BREAK>> 
<<LOOP BACK>> 



Figure 10-23. FCHECK Intrinsic Example 
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should bring the operation to an orderly conclusion. The difference in treatment of these two 
priysiCcU u3.p€ iHcuT-tvcrs is r6jj.GCvGu. ^y tuG j.LlG sySi>Gin niuiniisics Wj.-i.sii uiis xiaQ uSin^ r@£iu, writes*!} or 
controlled is a magnetic tape device file. The following paragraphs discuss the characteristics of each 
appropriate intrinsic. 

FWRITE 

If the magnetic tape is unlabeled (as specified in the FOPEN intrinsic or :FILE command) and a 
user program attempts to write over or beyond the physical EOT marker, the FWRITE intrinsic 
returns an error condition code (CCL). The actual data has been written to the tape, and a call to 
FCHECK reveals a file error indicating END OF TAPE. All writes to the tape after the EOT tape 
marker has been crossed transfer the data successfully but return a CCL condition code until the 
tape crosses the EOT marker again in the reverse direction (rewind or backspace). 

If the magnetic tape is labeled (as specified in the FOPEN intrinsic or :FILE command), a CCL 
condition code is not returned when the tape passes the EOT marker. Attempts to write to the tape 
after the EOT marker is encountered cause end of volume (EOV) labels to be written. A message 
then is printed on the operator's console requesting another volume (reel of tape) to be mounted. 

FREAD 

A user program can read data written over an EOT marker and beyond the marker into the tape 
trailer. The intrinsic returns no error condition code (CCL or CCG) and does not initiate a file 
system error code when the EOT marker is encountered. 

FSPACE 

A user program can space records over or beyond the EOT marker without receiving an error 
condition code (CCL or CCG) or a file system error. The intrinsic does, however, return a CCG 
condition code when a logical file mark is encountered. If the user program attempts to backspace 
records over the BOT marker, the intrinsic returns a CCG condition code and remains positioned on 
the BOT marker. 

FCONTROL (WRITE EOF) 

If a user program writes a logical end of file (EOF) mark on a magnetic tape over the reflective EOT 
marker, or in the tape trailer after the marker, the FCONTROL intrinsic returns an error condition 
code (CCL) and sets a file system error to indicate END OF TAPE. The file mark is actually written 
to the tape. 

FCONTROL (FORWARD SPACE TO FILE MARK) 

A user program which spaces forward to logical tape file marks (EOFs) with the FCONTROL 
intrinsic cannot detect passing the physical EOT marker. No special condition code is returned. 

FCONTROL (BACKWARD SPACE TO FILE MARK) 

The EOT reflective marker is not detected b" FCONTROL during backspace file (EOF) operations. 
If the intrinsic discovers a BOT marker before it finds a logical EOF, it returns a condition code 
of CCE and treats the BOT as if it were a logical EOF. Subsequent backspace file operations 
requested when the file is at BOT are treated as errors and return a CCL condition code and set a 
file system error to indicate BOT and BACKSPACE TAPE. 
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In summary, only those intrinsics which cause the magnetic tape to write information are capable of 
sensing the physical EOT marker. If a program designed to read a magnetic tape needed to detect 
the EOT marker, it could be done by using the FCONTROL intrinsic to read the physical status of 
the tape drive itself. When the drive passes the EOT marker and is moving in the forward direction, 
tape status bit 5 (%2000) is set and remains on until the drive detects the EOT marker during a 
rewind or backspace operation. Under normal circumstances, however, it is not necessary to check 
for EOT during read operations. The responsibility for detecting end of tape and concluding tape 
operations in an orderly manner belongs to the program which originally created (wrote) the tape. 

A program which needed to create a multi-volume (multiple reel) tape file would normally write 
tape records until the status returned from FWRITE indicated an EOT condition. Writing could be 
continued in a limited manner to reach a logical point at which to break the file. Then several file 
marks and a trailing tape label would typically be added, the tape rewound, another reel mounted, 
and the data transfer continued. The program designed to read such a multi-volume file must expect 
to find and check for the EOF and label sequence written by the tape's creator. Since the logical 
end of the tape may be somewhat past the physical EOT marker, the format and conventions used 
to create the tape are of more importance than determining the location of the EOT. 



END-OF-FILE MARKS ON MAGNETIC TAPE 

An FWRITE to magnetic tape, followed by any intrinsic call which reverses tape motion (for 
example, backspace a record, backspace a file, or rewind) causes the file system to write an EOF 
mark before initiating the reverse motion. 

For example, if a user program has just written several data records to magnetic tape, writes a file 
mark, rewinds the tape, and closes the file, the tape file will be terminated by two file marks (EOF). 
The first of these was requested by the user by calling FCONTROL to write an EOF, and the 
second was provided by the system because the direction of tape motion had been reversed after a 
write (rewind). See below. 



RECORD 
1 



RECORD 
2 



RECORD 



SPACING FILE MARKS 

When you space forward to a tape mark (EOF), the tape recording heads have just read the EOF 
and are positioned beyond it, as follows: 



B 




E 




E 















T 




F 




T 



"S 



BEFORE 



■O 



AFTER 
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When you space backward to a tape mark (EOF), the mark is recognized as the tape travels in the 
reverse direction. The tape heads then are left positioned just in front of the EOF that was read, as 
follows: 



B 




E 




E 















T 




F 




T 



{? 



AFTER 



17 



BEFORE 



NOTE 

BOT (beginning of tape) and EOT (end of tape) correspond 
to the reflective markers on the reel of magnetic tape. 

When FREAD has found a logical file mark and returned a condition code of CCG, the EOF mark 
has been read and the tape heads are positioned immediately following the mark (similar to space 
forward to tape mark above). 



USING THE FCLOSE INTRINSIC WITH MAGNETIC TAPE 

The operation of the FCLOSE intrinsic as used with unlabeled magnetic tape is outlined in the 

flowchart of Figure 10-24. 

Note that a tape closed with the temporary no-rewind disposition will be rewound and unloaded if 
certain additional conditions are not met. If is possible for a single process to FOPEN a magnetic 
tape device using a device class and later FOPEN the same device again using its logical device 
number. This may be done in such a manner that both magnetic tape files are open concurrently. 
The second FOPEN does not require any operator intervention (for example, for device allocation). 
When FOPEN/FCLOSE calls are arranged in a nested fashion, tape files may be closed without 
deallocating the physical device, as follows: 



FOPEN 



allocate tape 



FOPEN 



FCLOSE 



FOPEN 



FCLOSE 



FCLOSE 



allocated 



deallocate tape 



Such nesting of FOPEN/FCLOSE pairs is required to keep an FCLOSED tape from rewinding. A 
f ono ^locoH ■kH+v. the tpmnntarv nn-rpwinrf disnosition will be rewound and unloaded unless the 
process closing it has another file currently open on the device. 



Note also that when a temporary no-wind tape is deallocated, the file system has not placed an 
end-of-file mark at the end of the data file. 
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NO 



(NO CHANGE) 

1 (SAVE PERM) 

2 (SAVE TEMP) 
4 (DELETE) 




WRITE EOF MARK 
ON TAPE. 
REWIND TAPE 




REWIND AND 
UNLOAD TAPE - 
SETOFF LINE 




3 (TEMP-NO REWIND) 



REWIND 
TAPE 




REWIND & UNLOAD 
TAPE 

(DRIVE GOES 
OFFLINE) 



I 



DEALLOCATE THE 
MAGNETIC TAPE 
DEVICE 






1 147028-01 



Figure 10-24. Using the FLCOSE Intrinsic with Unlabeled Magnetic Tape 
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There are two standard formats for labels in common use: IBM and ANSI. They differ mainly in 
that the IBM labels are written in EBCDIC, not ASCII. The MPE tape labels facility can read and 
write labeled tapes that conform to the ANSI standard, and can read tapes that conform to the 
IBM standard. Only ANSI standard tapes support file lockwords. 

OPERATOR INTERVENTION 

When a tape is mounted and put on-line, an interrupt occurs which causes the label on a labeled 
tape to be read. In this case, the volume name, and, unless the tape is the first volume of a volume 
set, the volume set name, are reported on the operator's console. 

When an FOPEN for a labeled tape is executed, MPE checks to see whether a tape which satisfies 
the request is mounted. If so, it is assigned without operator intervention. Otherwise, a message is 
generated on the system console directing the operator to mount the required tape. If the operator 
mounts a suitable labeled tape, MPE assigns it to the requesting process, and no further operator 
intervention is required. If, however, the FOPEN specifies a write operation, and a blank tape is 
mounted, the operator must : REPLY to the request in order to assign it to the requestor. If the 
operator refuses the request with a : REPLY PIN,0, the FOPEN will fail with FSERR55 - Device 
Unavailable. 

The FCLOSE intrinsic can be used to maintain position when creating or reading a labeled tape file 
that is part of a volume set. If you close the file with a disposition code of 3 or 4, the tape does not 
rewind, but remains positioned at the next file. If you close the file with a disposition code of 2, 
the tape rewinds to the beginning of the file but is not unloaded. A subsequent request to open the 
file does not reposition the tape if the sequence (seq) subparameter is NEXT, or default. A disposi- 
tion code of (no change) or 1 (save permanent) implies the close of an entire volume set. 

UPDATING MAGNETIC TAPE FILES 

As a physical data storage device, magnetic tape is not designed to enable the replacement of a 
single record in an existing file. An attempt to perform this type of operation will cause problems in 
maintaining the integrity of records on the tape. Magnetic tape files, therefore, should not be 
maintained (updated) on an individual record basis but should be updated during copy operations 
from one file to another. 



- J! _J.J 



As an example of the type of problems tnat can occur, consider me resuius ui attempting tu irau a 
tape record, modify its data, backspace the tape, and overwrite the original record, as follows: 



FREAD 



\ 



BACKSPACE 

RECORD 

FIX DATA 
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MPE TAPE LABELS 

MPE provides a means whereby you can read and write labels on magnetic tape files. Labeled 
magnetic tape files are intended to provide for: 

1. A permanent identification for tape reels or volumes. 

2. Additional security, to protect against accidental over-writing or unauthorized access to 
files. 

3. Easy access to files which extend over more than one volume. 

4. More than one file on a volume. 

5. Retrieval of files by file names. 

6. Facilitating information interchange between computer systems. 

Each tape volume, when first written, is assigned a unique identifier, up to six printable characters, 
to permanently identify it. This identifier is the Volume Name. It is often strictly numeric, so that 
volumes in an installation's library can be sorted and stored by this number. 

A collection of volumes containing one or a related group of files is called a volume set. The volume 
name of the first reel in the set is taken as the Volume Set Name. 

Each file on a labeled tape has a header label or labels, which contain the name of the file, the 
sequential position of the file in the volume set, and the sequential number of the volume of the 
file if the file extends over more than one volume. They may optionally contain the record and 
block size, a file lockword, and whether the file is ASCII or binary. 

When opening a labeled tape file to be read, you must specify the Volume Set Name. This may 
appear either in a file equation LABEL = parameter, or in the FORMSMSG parameter of FOPEN; 
if it appears in neither place, the console operator will be asked for the Volume Set Name. One 
may also specify either that a specified file name is to be sought within the volume set, or merely 
that the next sequential file is to be accessed. If no file follows, then FOPEN will return an End of 
Volume Set error (FSERR123). 

When opening a labeled tape file to be written, the volume set name is specified as for reading. 
One may request a specific named file, or that the next sequential file be written, or that a file be 
added to the end of the volume set. An End of Volume Set error will be reported if a specific 
named file is requested but is not found. Of course, if there are other files following the file to be 
written, the contents of those files will be lost. 

You may close a file without closing the volume set containing it. What this means is that s subse- 
quent FOPEN specifying the same volume set name will be able to access a file on the currently 
mounted volume of the volume set without operator intervention. The volume thus accessed need 
not be the first one in the volume set. 
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If the replacement differed at all in size from the original record, the result would not simply be an 
update of the record. A replacement record of greater length than the original record would 
overwrite (destroy) a portion of the next record on the tape, as shown below. 



IRG: INTER-RECORD GAP -THE HARDWARE 
DEVICE CONTROLLER PLACES A GAP 
(UNRECORDED TAPE) BETWEEN 
ADJACENT DATA FIELDS. 



BEFORE 




RECORD 
2 



RECORD 
3 




AFTER 




REMAINS OF RECORD 3 



On the other hand, if the length of the replacement record is less than that of the original record, a 
portion of the original record will still remain on the tape as shown below. 



BEFORE 




AFTER 










1 




1 


R 






R 


G 




=3 


G 




REMAINS OF OLD RECORD 2 
NEW RECORD 2 



In either of the two cases shown, the partial records remaining would cause magnetic tape read 
errors and would create problems in subsequent processing of the tape file. 

Even with replacement records of the same size as the original records, errors can still result. 
Mechanical and timing variations from one magnetic tape drive to another can create substantial 
differences in the actual length of tape records containing the same amount of data. Magnetic tape 
standards, for example, permit the inter-record gap (IRG) to vary in length from 0.5 to 0.7 inches. 
Similar variations may occur to a lesser extent in the spacing of the actual data bytes recorded. In 
short, the variation of a number of hardware factors which are beyond the user's control can affect 
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the physical length of the tape records written. For this reason, always update tape files during copy 
operations from one tape to another. 

READING AND WRITING AN UNLABELED MAGNETIC TAPE FILE 

Figure 10-25 contains a program that copies an unlabeled magnetic tape file into another file on the 
same reel of tape. 

The FOPEN intrinsic call 

MT:=FOPEN(NAME,%201,%4,66,CLASS); 

opens the magnetic tape file. The parameters specified are 

formaldesignator MAGTAPE, which is contained in the byte array NAME 

foptions %201, for which the bit pattern is as follows: 



Bits 

Binary 

Octal 






1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 











U 














1 




















1 


















2 













1 





aoptions 



The above bit pattern specifies the following file options: 

Domain: Old permanent file. Bits (14:2) = 01. 

ASCII/Binary: Binary. Bit (13:1) = 0. 

Default Designator: Same as formal file designator. Bits (10:3) = 000. 

Record Format: Undefined length. Bits (8:2) = 10. 

%4, for which the bit pattern is as follows: 






1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 


Bits 


































n 


1 


n 


n 


Tjiriarv 






























4 




Octal 



The above bit pattern specifies the following access options: 
Access Type: Input/output access. Bits (12:4) = 0100. 
66 words. 

d ev ice TAPE, contained in the byte array CLASS. 

All other parameters are omitted from the FOPEN intrinsic call. 



recsize 
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0O001OO0 


00000 


00002000 


00000 


00003000 


00000 1 


00004000 


00000 1 


00005000 


00005 1 


00006000 


00004 1 


00007000 


00004 1 


00008000 


00OO4 1 


00009000 


00004 1 


OOOIOOOO 


00004 1 


00011000 


00004 1 


00012000 


00004 1 


00013000 


00000 1 


00014000 


00000 1 


00015000 


00000 1 


00016000 


00000 2 


00017000 


00002 2 


oooieooo 


00004 2 


00019000 


00000 1 


00020000 


ooooo i 


00021000 


ooooo i 


00022000 


00000 1 


00023000 


00012 1 


00024000 


00016 1 


00025000 


00016 1 


00026000 


00016 1 


00027000 


00024 1 


00028000 


00030 1 


00028100 


00033 1 


00029000 


00033 1 


00030000 


00037 1 


00031000 


00043 1 


00032000 


00046 1 


00032100 


00052 1 


00033000 


00052 1 


00034000 


00057 1 


00035000 


00063 1 


00036000 


00063 1 


00037000 


00067 1 


0003AOOO 


00073 1 


00039000 


00077 1 


00040000 


00103 1 


00041000 


00103 1 


00042000 


00104 1 


00043O00 


00104 1 


00044000 


00107 1 


00045000 


00113 1 


00047000 


00115 1 


00048000 


00115 1 


00049000 


00115 1 


00050000 


00121 1 


00051000 


00125 1 


00052000 


00125 1 


00053000 


00130 1 


OO054O00 


00134 1 


00055000 


00134 1 



tCONTROL USLINIT 
BEGIN 

INTEGER MT.RECO' POSITION j=0,LGTH? 

BYTE APRAY NAME (0 J 7) : =»MAGTAPE "t 

RYTE ARRAY CLASS (0 :4 ): =»TAPE "I 

ARRAY BUFFER(0:65) J 

LOGICAL OUMMYt 

INTRINSIC FOPEN.FREAD.FCONTROL.FSPACE 
PRINT»FILE»INFO,QUITI 

PROCEDURE FlLERROR(FILENO,QUITMO> » 
VALUE FILENO.QUITNOJ 
INTEGER FILENO,QUITNO» 
REGIN 

PRINT'FILE'INFO(FILENO) I 
QUIT(QUITNO) » 
END* 

<<END OF DECLARATI0NS>> 

MT:=FOPEN (NAME. «201,%4, 66, CLASS) » 
IF < THEN FILERROR(MT.l) J 

COPY»LOOP: 

IF > THEN GO DONE J 

FCONTROl(MT,7,OLiNMYM 
IF < THEN FILERftOR(MT,3)t 
FSPACF(MT.RECD«P0S1T10N) I 
IF <> THEN FI|_ERR0R(MT,4M 

FWRITEIMT, BUFFER, LGTH, 0)1 
IF <> THEN flLERROR(MT,5)l 

-f-OSTftOt m7*& + DtiMMn f 

IF < JH?t4 Frtr»t*OR>f»T,MI 

FCONTROL«MT,8,OUMMY)| 

IF < THFN FILERROR<NT,7H 

RECO»POSlTIONl«RECO»POSlTIWlt 

FSPACE(MT,RECD«P0S1TI0N)» 

«0 COPYtLOQP* 



»FWRITE,FCLOSE, 



PONFl : 



FC-««T«OL '« .S,%'MV; * 

IF < THFN FILF«R0H<MT.9)| 

FCLOSE(MT.O.O) ; 

IF < THEN FILERROR(MT,10M 



END. 



PRIMARY DB STORAGE=*007; SECONDARY DB STORAGE=*00 1 11 



<<MAG TAPE» 
<<CHECK FOR ERROR>> 



*><T*?»r file :» 

'4CHECK f» £»«&»}» 

<*wttK foe zm» 

«90 TO END FILE 1» 
«CHECK FOR ERROR» 

«BACK TO EMO FILE 1» 

<<CHECK FOR ERRoR» 
<<INCR RECORD CNTR>> 
«NEXT FILE 1 RECD» 

*<c**ec* ran zmm» 



<<REWIND T«PE» 
«CHEC> FOP EH* ■- .■•. 

<<MAG TAPE>> 
<<CHECK FOR ERR0R>> 



Figure 10-25. Unlabeled Magnetic Tape Example 
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Once the file is opened, the file number (used by other file system intrinsics when referencing this 
file) is returned to the variable MT. 

The statement 

IF < THEN FILERROR(MT,l); 

checks the condition code and, if it is CCL, calls the error-check procedure FILERROR. The 
FILERROR procedure prints a FILE INFORMATION DISPLAY on the standard list device, 
enabling you to determine the error number returned by FOPEN, then aborts the program's 
process. 

The tape format before the copy operation is started is as follows: 



RECORD 
1 



RECORD 
2 




The statement 

LGTH:=FREAD(MT,BUFFER,66); 

reads a record from the file designated by MT and transfers this record to BUFFER. The statement 
reads up to 66 words from the record, then returns a positive value to LGTH indicating the actual 
length of the information transferred. 

The statement 

FCONTROL(MT,7,DUMMY); 

spaces forward to the EOF tape mark (the end of the file). As you recall from the paragraph 
"SPACING FILE MARKS", the recording head actually is positioned slightly beyond the EOF file 
mark. Now the statement 

FSPACE'MT E.EGD'POSITION); 

spaces the tape to the point where the first record (RECD'POSITION = 0, see statement number 3 
in the program) of the second file is to begin. The statement 

FWRITE(MT,BUFFER,LGTH,0); 
writes the record contained in the array BUFFER into this record. 
The statement 

FCONTROL(MT,8,DUMMY); 
spaces back to the end of file 1 (the EOF mark) and the statement 
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FCONTROL( MT,8,DUMM Y ) ; 

then spaces back to the next tape mark (the start of file 1). 

The record position is set to the next record in file 1 by incrementing RECD'POSITION with the 
statement 

RECD'POSITION:=RECD'POSITION+l; 
and spaces ahead to that record with the statement 

FSPACE(MT,RECD'POSITION); 
and the copy loop is repeated. After the copy loop is repeated, the tape is as follows: 
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RECORD 
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RECORD 
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RECORD 
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FILE 1 



FILE 2 



Note that the reverse tape motion after a write creates an EOF mark (see end of file 2). 

The copy loop is repeated until the end of file 1 is reached, at which point program control is 
transferred to the statement label DONE. The tape then is rewound with the statement 

FCONTROL(MT,5,DUMMY); 

and closed with the same disposition (old permanent) as before. 

The format of the tape at the end of the copy operation is as follows: 



RECORD 
1 



RECORD 
2 



FILE 1 



RECORD 
n 



RECORD 
1 



RECORD 
2 



■v 

FILE2 



RECORD 
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Figure 10-26 shows a program that opens a labeled magnetic tape file and a disc file; reads the con- 
tents of the tape file and writes the records read to the disc file; closes the tape file; and, finally, 
closes the disc file as a permanent file. 

The statement 

FNOl:=FOPEN(FILIDl,%1004„DEV,LABELID); 
calls FOPEN to open the labeled magnetic tape file. The parameters specified are 
formaldesignator TAPEFILE, stored in the byte array FILID1. 

foptions %1004, for which the bit pattern is as follows : 






1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 




















1 




















1 





1 












1 




















5 





Bits 

Binary 

Octal 



aoptions 



The above bit pattern specifies the following file options: 

Domain: Old, permanent file, system file domain. 

Bits (14:2) = 01. 

ASCII/Binary: ASCII. Bit (13:1) = 1. 

File Designator: Actual file designator same as formal file designator. 

Bits (10:3) = 000. (Default) 
Record Format: Fixed length. Bits (8:2) = 00. (Default) 
Carriage Control: No carriage control. Bit (7:1) = 0. (Default) 
Labeled Tape: Labeled. Bit (6:1) = 1. 

5, for which the bit pattern is as follows: 






1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 









































1 





1 






























5 





Bits 

Binary 

Octal 



recsize 



device 



The above bit pattern specifies the following access options: 

Access Type: Update. Bits (12:4) = 0101. 

Default. 

TAPE, contained in the byte array DEV. 
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$CONTROL USLINIT 
BEGIN 

BYTE ARRAY FILID1 (0 : 8 ) J *"TAPEFILE "; 

BYTE ARRAY FILID2 (0 :3) :=" "; 

BYTE ARRAY LABELID(0 : 79) j = " .FIL001 , ANS, 12/31 til ; ■ ; 

BYTE ARRAY DEV(0: 4) : ="TAPE "; 

APPAY MSGBUF(0:35); 
ARRAY INBUFtO:39); 
ARRAY FIL'ID2(*)sFILID2; 

INTEGER FN01,FN02,LGTri; 

INTRINSIC FOpEN,FCLOSE,FREAD,FWRITE, READ, PRINT, PRINT'FILE* INFO, 
QUIT,CAU5EBREAK,FREADLABEL; 

PROCEDURE FILEPROR(FJLENO,QUITNO); 
VALUE QUITNO; 
INTEGER FILENO, QUITNO; 
BEGIN 

PRINT'FILE'INFO(FILENO); 
QUIT(QUITNO); 
END; 

<< END OF DECLARATIONS >> 

MOVE MSGBUFjs-NAHE OF NEW DISC FILE TO BE CREATED?"; 

PRINT(MSG6UF,-6,0); 

READ(FIL'1D2,4); « READ NAME OF NEW DISC FILE » 

FNOl:=FOPEN(FILIDl,%1001,5,,DEV,LABELID)J « OPEN LABELED 

IF < THFN TAPE FILE y> 

lF „ r ™ S « CHECK FOR ERROR » 

MOVE MSGBUF:s"CAN'T OPEN TAPE FILE"; 
PRINT(MSGBUF,-20,0); 
FILERRORCFNOl,!}; 
END; 

FN02:sFOPEN(FILID2,4,5); « OPEN NEW DISC FILE » 

IF < THEN « CHECK FOR ERROR » 

BEGIN 

MOVE MSGBUF;s"CAN»T OPEN DISC FILE"; 
PRINT(MSGBUF,«20,0); 
FILERROR(FN02,2); 
END; 

FREADLABEL(FN01,INBUF,40); « READ USER LABEL » 
IF <> THEN FILERRORCFNOl, 3); « CHECK FOR ERROR » 
PRINT(INBUF,40,0); 

READ'WRITE'LOOP! 

LGTH:sFREAD(FN01,INBUF,40); « READ RECORD FROM 

TAPE FILE » 



Figure 10-26. Opening a Labeled Magnetic Tape File (Sheet 1 of 2) 
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IF < THEN « CHECK FOR ERROR » 

BEGIN „„„. 

MOVE MSGBUF3=*CAN*T READ TAPE FILE"? 

PRINT(MSGBUF,«20»0); 

FILERROR(FNOi,4)f 

END; 
IF > THEN GO CLOSE1; « CHECK FOR END-OF-FILE » 

FWRITECFN02,INBUF,LGTH,0); « WRITE RECORD TO 

DISC FILE » 
IF <> THEN « CHECK FOR ERROR » 

BEGIN 

MOVE MSGBUFt="CAN'T WRITE TO DISC FILE"; 

PRINT(MSGBUF,-24,0); 

FILERR0PCFNO2.5); 
END? 

GOTO READ'WRITE'LOOP; 
CLOSE1: 

F C LOSE(FH01, 1.0)1 « CLOSE, REWIND. AND UNLOAD TAPE FILE » 
IF < THEN « CHECK FOR ERROR » 

BEGIN 

MOVE MSGBUF:="CAN»T CLOSE TAPE FILE"; 
PRINT(MSGBUF,-21,0); 
FILERROR(FNOi.6)j 
END; 

CLOSE2: 

FCLOSE(FNO2,1.0); « CLOSE DISC FILE AS 

PERMANENT FILE » 
IF < THEN « CHECK FOR ERROR » 

BEGIN 

MOVE MSGBUF:«"CAN'T CLOSE DISC FILE"; 
PRINT(MSGBUF,-21,0)» 

MOVE MSGBUFjs"CHECK FOR DUPLICATE NAME"; 
PRINT(MSGBUF,-24»0); 

MOVE MSGBUFs="FIX, THEN TYPE 'RESUME'"; 
PRINT(MSGBUF»-23.0); 
GOTO CLOSE2; « TRY AGAIN >> 
END; 
END. 



Figure 10-26. Opening a Labeled Magnetic Tape File (Sheet 2 of 2) 
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tape label Contained in the byte array LABELID (formmsg parameter). LABELID 

is declared with the value 

.FIL001.ANS, 12/31/77; 

(see statement number 5 in figure 10-26). Note that the tape label 
begins with a period and ends with a semi-colon. This is necessary to 
distinguish the tape label from a forms message (another use for this 
parameter). 

When the FOPEN intrinsic call executes, MPE sends a message to the system console, requesting the 
Console Operator to mount the tape labeled FIL001 (if it is not already mounted) . 

The statement 

FN02:=FOPEN(FILID2,4,5); 
opens a new disc file. 
The program then reads records from the tape file with the statement 

LGTH:=FREAD(FNOl,INBUF,40); 
and writes these records to the disc file with the statement 

FWRITE(FNO2JNBUF,LGTH,0); 

When all records in the tape file have been read, both files are closed. The disc file is saved as a per- 
manent file. 

WRITING A TAPE LABEL 

The MPE :FILE command or FOPEN intrinsic is used to write ANSI-standard tape labels (MPE will 
not write IBM-standard tape labels). See the MPE Commands Reference Manual for a discussion of 
writing tape labels with the :FILE command. 

The program shown in Figure 10-27 opens a magnetic tape file and writes a label on the file. 
The statement 

BYTE ARRAY LABELID(0:79): = ".FIL099,ANS,12/31/77,NEXT;"; 
declares a byte array of 80 bytes and initializes it to 
.FIL099,ANS,12/31/77,NEXT; 

which constitutes an ANSI-standard label. Note that the tape label begins with a period and ends 
with a semi-colon. This is necessary to distinguish the tape label from a forms message (which is 
another use for the same FOPEN parameter). The LABELID byte array will be used in the FOPEN 
intrinsic call to specify a file label as follows : 



Volume Identification: FIL099 
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SCONTROL USLINIT 
BEGIN 

BYTE ARRAY FILID1 C 0? 8 ) !*" "» 

BYTE ARRAY FILID2(0:8 ) t s'NEWTAPEl "; 

BYTE ARRAY LABELID(0I 79) »*" ,FIL099>ANS, 12/31 til .NEXT; " ; 

BYTE ARRAY DEV£0l4) :="TAPE "; 

ARRAY MSGBUFC0I35); 
ARRAY INBUF(0:39); 
ARRAY FIL'ID1(»)*FILID1> 
ARRAY USERLABLCOJ79); 

INTEGER FN01,FN02,LGTH; 

INTRINSIC FOPEN,FCLOSE,PRINT'FILE» INFO, QUIT, PRINT, READ, 
FWRITELABEL,FREAD,FWRITEf 

PROCEDURE FILERROR(FILENO,OUITNO) ; 
VALUE OUITNOJ 
INTEGER FILENO,QUITNO; 
BEGIN 

PRINT'FILE'INFO(FILENO) ; 
QUITtQUITNQ); 
END; 

« END OF DECLARATIONS » 

MOVE MSGBUF:*"NAME OF INPUT FILE?"; 

PRINT(MSGBUF,-19 t 0)» 

READ(FIL'IDl,-8)> « READ NAME OF INPUT FILE » 

FN01:sFOPEN(FILIDl,l,5) J « OPEN OLD DISC FILE » 
IF < THEN « CHECK FOR ERROR » 

BEGIN 

MOVE MSGBUF;="CAN'T OPEN DISC FILE"; 
PRINT(MSGBUF#-20»0); 
FlLERROR(FN01»l)> 
END; 

FN02i*FOPEN(FILID2,%1004,5,,DEV,LABELID); « OPEN NEW LABELED 

TAPE FILE » 
IF < THEN « CHECK FOR ERROR » 

BEGIN 

MOVE MSGBUF:*"CAN'T OPEN TAPE FILE"; 
PRINT(MSGBUF#-20»0); 
FILERR0R(FN02»2)» 
END; 

MOVE USERLABL:=" "; 

MOVE uSERLABLtsuSERLABL(0)r(40); 

MOVE USERLABLt*"UHLl USER HEADER LABEL NO. 1"; 

FWRITELABEL(FNO2,USERLABL,40,0); « WRITE USER HEADER LABEL » 

IF <> THEN FILERPOP(FN02,3); << CHECK FOR ERROR >> 

READ'WRITE'LOOPJ 



Figure 10-27. Writing a Tape Label (Sheet 1 of 2) 
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LGTHj*FREAD(FN01,INBUF,40); « READ RECORD FROM DISC FILE » 
IF < THEN « CHECK FOP ERROR » 

BEGIN 

MOVE M5GBUF|*"CAN'T READ DISC FILE"| 
PRINT(MSGBUF,-20,0); 
FlLERROR(FNOi,4)> 
END; 
IF > THEN GO CLOSE; « CHECK FOP END-OF-FILE » 

FWRITE(FNO2,INBUF,LGTH,0); « WRITE RECORD TO LABELED TAPE FILE » 
IF <> THEN « CHECK FOR ERROR » 

BEGIN 

MOVE MSGBUF|*"CAN»T WRITE TO TAPE FILE"; 
PRINT(MSGBUF,-24rO); 
FILERROR(FN02,5); 
END; 

CLOSEI 

FCL05ECFNOi,0,0); « CLOSE DISC FILE » 
IF < THEN « CHECK FOR ERROR >> 

BEGIN 

MOVE MSGBUFt*"CAN'T CLOSE DISC FILE"; 
PRINT(MSGBUF,-21,0); 
FILERROR(FN01,6); 
END; 

FCLOSE(FN02,i,0); « CLOSE, REWIND, AND UNLOAD TAPE FILE » 
IF < THEN « CHECK FOR ERROR » 

BEGIN 

MOVE MSGBUF:»»CAN»T CLOSE TAPE FILE"; 
PRINT(MSGBUF,-21»0); 
FILERROR(FN02,7); 
END; 
END. 



Figure 10-27. Writing a Tape Label (Sheet 2 of 2) 
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Label Type: ANS (ANSI) 

Expiration Date: 12/31/77. This is the date after which the file can be overwritten. If 

you attempt to overwrite the file before this date, MPE will send a mes- 
sage to the Console Operator asking for confirmation that such is really 
desired. This affords an extra measure of protection against inadver- 
tently destroying a tape by overwriting when a WRITE RING is left in 
the tape by mistake. 

sequence: NEXT. Signifies that the file is to be positioned at the next file on the tape. 

The statement 

FNO2:=FOPEN(FILID2,%1004,5„DEV,LABELID,l); 

opens a new tape file and writes the tape label as specified by LABELID. 

READING A LABELED MAGNETIC TAPE FILE 

Once a labeled tape file has been opened, the FREAD intrinsic may be used in the same manner as 
on an unlabeled tape file. The system defaults to the blocksize, recordsize and file format on the 
tape label if these parameters are not specified. You can call FGETINFO or FFILEINFO to get 
these values. 

The program shown in Figure 10-26 reads a labeled magnetic tape file in sequential order. 
The labeled tape file is opened with the statement 

FNOl:=FOPEN(FILIDl,%1005,5„DEV,LABELID); 
The file label is contained in the byte array LABELID. 
The block of statements 



GOTO READ'WRITE'LOOP; 
form a read/write loop. Records are read from the tape file in sequential order with the statement 

LGTH:=FREAD(FNOl,INBUF,40); 
and written to a disc file with the statement 

FWRITE (FNO2,INBUF,LGTH,0); 
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WRITING TO A LABELED MAGNETIC TAPE FILE 

Writing records to a labeled tape file is slightly different than writing to an unlabeled tape file as 
follows : 

If the magnetic tape is unlabeled and a user program attempts to write over or beyond the 
physical EOT marker, the FWRITE intrinsic returns an error condition code (CCL). The actual 
data has been written to the tape, and a call to FCHECK reveals a file error indicating END OF 
TAPE. All writes to the tape after the EOT tape marker has been crossed transfer the data 
successfully but return a CCL condition code until the tape crosses the EOT marker again in 
the reverse direction (rewind or backspace). 

If the magnetic tape is labeled, a CCL condition code is not returned when the tape passes the 
EOT marker. Attempts to write to the tape after the EOT marker is encountered cause end of 
volume (EOV) labels to be written. A message then is printed on the operator's console request- 
ing another volume (reel of tape) to be mounted. 

The program shown in Figure 10-27 opens an existing disc file and a new labeled tape file, reads 
records from the disc file and writes these records to the tape file. If an attempt is made to write 
records on the tape beyond the EOT marker, MPE will write EOV1 and EOV2 labels on the tape 
and request the Console Operator to mount another reel of tape. 

The statement 

FWRITE(FNO2,INBUF,LGTH,0); 

writes the contents of array INBUF onto the tape file signified by FN02. The LGTH parameter 
specifies the number of words to be written. 

WRITING A USER-DEFINED FILE LABEL ON A LABELED TAPE FILE 

User-defined labels are used to further identify files and may be used in addition to the ANSI-stan- 
dard labels. Note that user-defined labels may not be written on unlabeled magnetic tape files. 

User-defined labels are written on files with the FWRITELABEL intrinsic instead of the FOPEN 
intrinsic (as is the case for writing ANSI-standard labels). 

User-defined labels for labeled tape files are slightly different than user-defined labels for disc files 
in that user-defined labels for tape files must be 80 bytes (40 words) in length. The tape label infor- 
mation need not occupy all 80 bytes, however, and you can set unused portions of the space equal 
to blanks. 

Figure 10-27 contains a program that opens a new tape file and writes an ANSI-standard label on 
this file, then writes a user-defined header label with the FWRITELABEL intrinsic. 

The statement 

FNO2:=FOPEN(FILID2,%1004,5„DEV,LABELID,l); 

opens a new tape file named NEWTAPE1 (the name is contained in byte array FILID2), writes an 
ANSI-standard label (contained in the byte array LABELID) to the file. 
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Labeled Tapes 

Since it is important that tape density be an attribute of an entire volume set, the density of a 
labeled tape is determined by the first FOPEN, the volume set open. Density specified on all subse- 
quent FOPENs will be ignored until the entire volume set is unloaded from the tape drive. Note that 
the file system will rewrite VOL 1 labels in certain situations, such as in the case of rewriting a 
labeled tape at 6250 BPI which had previously been written at 1600 BPI. This is to prevent creating 
a multireel labeled volume set containing volumes of different densities. 

If the user omits the DEN keyword parameter (see FOPEN in Section II), or specifies the keyword 
and omits the density selection when writing a new label on a previously unlabeled tape, the file 
system assigns a default density (in this case 6250 BPI) to the FOPEN request. 

If a volume set FOPEN takes the default density, and is satisfied by the proper unlabeled tape 
volume, the density of the volume is left unchanged. However, if a volume set open is satisfied by 
a proper labeled tape volume, and the density of the tape does not match the specific density 
requested by the user, the VOL1 label may be rewritten at a new density. If the volume set is 
currently empty (which is determined by the presence of a tape mark after the VOL1 header), or if 
the volume set open specifies NEXT as the sequence type, the VOL1 label is rewritten. In all other 
cases the volume set density is unchanged. 

When a reel switch occurs while writing a file to a labeled tape, each succeeding volume is written 
at the same density as its predecessor, i.e., all volumes are written at the same density as the first. 
Therefore, if a reel switch request is satisfied by a labeled tape, its VOL1 label is rewritten if the 
label's density is different from that of the volume set. This ensures that all volumes of a labeled 
volume set are written at the same density. 



Unlabeled Tapes 

Since unlabeled tapes may be accessed as many different files simultaneously (providing that the 
FOPENs occur in the same process tree), and may be returned to load point using several different 
file system Intrinsics, the default density selection is somewhat different for unlabeled tapes. If a 
write operation occurs while an unlabeled tape is at load point, the density of the tape will be set 
to the density requested by the most recent FOPEN which had write access to the tape. 

The default density for the first FOPEN of a variable density tape drive is 6250 BPI. For any subse- 
quent FOPENs, the density specified by the previous FOPEN is retained. Note, however, that any 
FOPEN which specifies a particular density (user supplied, not default), and has write access to the 
file takes precedence over all previous FOPENs. Remember that density can be changed only at load 
point, and if the next operation is a write. 

When an application does its own unlabeled tape reel management, all subsequent reels of a volume 
set will be automatically set to the density of the first reel, providing that no FOPENs which change 
the density of the tape drive occur during the writing of the reels. In this case, it would be possible 
to generate volumes of different densities (i.e., one volume at 1600 BPI, and one volume at 6250 
BPI). Note, however, that it is not possible in any case to write a tape at two different densities, 
since density can only be changed at load point. 
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Determining Tape Density 

The FFILENO Intrinsic will return the density of a tape file if item number 46 is specified. The 
density will be returned as an integer, either 1600 or 6250, signifying BPI. This item number is 
only valid for files residing on variable density tape drives. For any other requests, the Intrinsic 
will return a zero. 

When a tape is not at load point at the time of the call, the intrinsic returns the actual density of 
the tape. If the Intrinsic is called while the tape is at load point (only possible for unlabeled 
tapes), a value based on the FOPEN access is returned. If the tape was accessed READ only, the 
Intrinsic returns the actual density of the tape. If the tape was accessed in any other mode, the 
Intrinsic assumes that the next operation will be a WRITE, and returns the tape density requested at 
FOPEN time. 

SPACING ON DISC OR TAPE FILES 

You can space forward or backward on a disc or tape file (containing non-variable-length records) 
with the FSPACE intrinsic. (This intrinsic resets the logical record pointer.) 
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The statements 

MOVE USERL ABL : = " " ; 

MOVE USERLAB;: = USERLABL(0),(40), 

fill the array USERLABL with 80 ASCII blanks (40 words), and the statement 

MOVE USERLABL: = "UHL1 USER HEADER HEADER LABEL NO. 1"; 

moves the desired user label into the first 35 bytes of the array (replacing the blanks). 

The statement 

FWRITELABEL(FNO2,USERLABEL,40,0); 

writes all 80 characters into the file as a user-defined header label. 

Note that in order to write a user-defined header label, the FWRITELABEL intrinsic must be called 
before the first FWRITE to the file. (MPE will write user-defined trailer labels if FWRITELABEL is 
called after the first FWRITE). 

READING A USER-DEFINED FILE LABEL ON A LABELED TAPE FILE 

The FREADLABEL intrinsic is used to read a user-defined label on a labeled magnetic tape file. 
To read a user-defined header label, the FREADLABEL intrinsic must be called before the first 
FREAD is issued for the file. Execution of the first FREAD causes MPE to skip past any unread 
user-defined header labels. 

If Figure 10-26, the statement 

FREADLABEL(FNOl,INBUF,40); 

reads a user-defined header label. The parameters specified are as follows: 

FN02 The file number as returned by the FOPEN intrinsic. 

INBUF An array to which the label is transferred. 

40 Specifies the number of words to be read. 

DENSITY SELECTION ON LABELED AND UNLABELED TAPES 

The following information applies to density selection for variable density tape drives. Density, if 
specified, is ignored by tape drives which operate only at one density. 
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In figure 10-25, the statement 

FSPACE(MT,RECD'POSITION); 

is used to space a tape file. The parameters specified are 

filenum Supplied by MT, which was assigned the file number when the FOPEN 

intrinsic opened the file. 

displacement Specified by RECD'POSITION, which signifies the number of logical 

records to be spaced and the direction of displacement. (A positive 
value signifies forward spacing, a negative value signifies backward 
spacing.) 

In the example, the value of RECD'POSITION is positive and the spacing is forward. 
RECD'POSITION is incremented by 1 each time the copy loop is executed, resulting in a sequential 
spacing of the file, thus enabling the program to read logical record 0, then 1, 2, and so forth. 

DIRECTING FILE CONTROL OPERATIONS 

You can perform various control operations on a file (or the device on which the file resides) by 
issuing the FCONTROL intrinsic call. These operations include: supplying a printer or terminal 
carriage-control directive, verifying input/output, reading the hardware status word pertaining to 
the device on which the file resides, setting a terminal's time-out interval, rewinding the file, writing 
an end-of-file indicator, and skipping forward or backward to a tape mark. (The FCONTROL 
intrinsic can also be used to perform various terminal functions, such as changing the terminal speed 
or enabling parity checking. These applications of FCONTROL are described in Section V.) 

Figure 10-25 contains four examples of FCONTROL which manipulate a tape file. 

The first statement (statement number 29) 

FCONTROL(MT,7,DUMMY); 
spaces forward to a tape mark (EOF). 
The next two statements (statement numbers 36 and 38) are both as follows: 

FCONTROL(MT,8,DUMMY); 

These statements space backward to tape marks. The first statement finds the EOF mark (the head 
was positioned beyond the EOF mark) and the second statement spaces backward again to find the 
beginning of the same file. 

The last FCONTROL statement in the program 

FCONTROL(MT,5,DUMMY); 

rewinds the tape. 
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Note that the parameter DUMMY has no function in the application of FCONTROL in figure 3-25 
and is supplied merely because all parameters of FCONTROL are required parameters. 

RESETTING THE LOGICAL RECORD POINTER 

You can reset the logical record pointer for a disc file, containing only fixed-length or 
undefined-length records, to any logical record in the file with the FPOINT intrinsic. When the next 
FREAD or FWRITE request is issued for the file, this record will be the one read or written. 

As an example, to position the logical record pointer to the 40th logical record in the file FILE1, 
you would use the following intrinsic call: 

FPOINT(FILEl,39D); 

Remember that the first logical record in a file is record zero and that the D suffix denotes a double 
integer value in SPL. 

DECLARING ACCESS-MODE OPTIONS 

You can activate or deactivate the following access-mode options by issuing the FSETMODE 

• ■_: „:„ ™"- —± n -=—!- j---- <-- ~~~~-r~*-i ^^+if.oi nntniit worifipnt.inn terminal control bv the user. 

intrinsic can: automauiu euOi icwvaj, ^i^"' ^^^v... .~— ~> > - c jU "* lv - 

and terminal binary data mode. The access-mode options established remain in effect until another 

FSETMODE call is issued or until the file is closed. The FSETMODE intrinsic applies to files on all 

devices. 

The following FSETMODE intrinsic call 

FSETMODE(FILEl,%2); 

establishes access-mode options as outlined below. The parameters specified are 

filenum Designated by FILE1, which was assigned the file number by FOPEN 

when the file was opened. (It is a terminal in this example.) 



mode flags 



%2, for which the bit pattern is as follows: 
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Bits 
Binary 
Octal I 



The above bit pattern specifies the following access-mode options: 

Critical Output Verification: 

All physical output of blocks to the file is to be verified as physically 
complete before control returns from a write intrinsic to your program. 
For each successful logical write operation, a condition code (CCE) is 
returned immediately to your program. Bit (14:1) = 1. 



JUL 1981 



10-91 



Tape Error Recovery: 

A recovered tape error is reported with the CCE condition code. Bit 

(12:1) = 0. 

Terminal Control by User: 

MPE will issue carriage return/linefeed. Bit (13:1) = 0. 

DETERMINING INTERACTIVE AND DUPLICATIVE FILE PAIRS 

An input file and a list file are said to be interactive if a real-time dialogue can be established 
between a program and a person using the list file as a channel for programmatic requests, with 
appropriate responses from a person using the input file. For example, an input file and a list file 
opened to the same teleprinting terminal (for a session) would constitute an interactive pair. An 
input file and a list file are said to be duplicative when input from the former is duplicated 
automatically on the latter. For example, input from a card reader is printed on a line printer. 

You can determine whether a pair of files is interactive or duplicative with the FRELATE intrinsic 
call. (The interactive/duplicative attributes of a file pair do not change between the time it is 
opened and the time it is closed.) 

The FRELATE intrinsic applies to files on all devices. 

To determine if the input file INFILE and the list file LISTFILE are interactive or duplicative, you 
could issue the following FRELATE intrinsic call. 

ABLE:=FRELATE(INFILE,LISTFILE); 

INFILE and LISTFILE are identifiers specifying the file numbers of the two files. (The file numbers 
were assigned to INFILE and LISTFILE when the FOPEN intrinsic opened the files.) 

A word is returned to ABLE showing whether the files are interactive or duplicative. The word 
returned contains two significant bits, and 15. 

If bit 15 = 1, INFILE and LISTFILE form an interactive pair. 

If bit 15 = 0, INFILE and LISTFILE do not form an interactive pair. 

If bit = 1, INFILE and LISTFILE form a duplicative pair. 

If bit = 0, INFILE and LISTFILE do not form a duplicative pair. 
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USER LOGGING 

The MPE IV User Logging Facility provides a flexible transaction logging capability which enables 
vou to journalize additions and modifications to your data bases and subsystem files. User logging 
permits you to iournalize on two mediums: tape and disc. When a tape file is used, journal entries 
£f saved on a dedicated magnetic tape file outside the domain of the sy stem -. f Wh ^ a „^ n ^ 
used the journal entries are saved in a special disc file you create specifically for logging 
transactions. It is also possible to organize your applications so that both mediums are used for 
logging. 

Logging is done programmatically by means of three intrinsics: OP ENLOG WRITE LOG and 
CLOSELOG OPENLOG provides access to the logging facility. CLOSELOG closes access to he 
system and' WRITELOG writes journal entries to the logging file. This creates a copy of the 
data-set's modifications. If the data-set is lost, the logging tape or disc file can be used in 
conjunction with a backup copy of the file to recover the lost transactions. 

HOW USER LOGGING WORKS 

The User Logging Facility contains a buffer file, a logging process, a logging file for each process, 
and a data segment containing a communications area and a buffer for each active log file, (bee 
Figure 10-28) The function of two of these segments, the logging process and the logging buffer 
file, varies for disc file logging and tape file logging. 

When you access the logging facility and request tape files, your entries are placed in the buffer area 
of the logging data segment. Once this buffer area is full, the contents are written to the logging 
buffer fUe on disc. If there is no space available, two things can happen according to the MODh, you 
specified. 

If you indicated no wait in the mode parameter, the communications 
area of the data segment sends an error message indicating your trans- 
action has not been completed, and you need to resubmit your request 
(similar to NOWAITIO). 

If you indicated wait in the mode parameter, your process is sus- 
pended until the logging process writes the contents of the buffer to the 
media specified, tape or disc, and then reactivates your process (similar 
to WAITIO). 
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Figure 10-28, User Logging Facility 



The logging process acts as an interface between the logging buffer file and the logging tape file. The 
logging process writes records to the mag tape destination you have requested. This process is 
independent of your process; thus the logging process can be writing records from the disc buffer to 
tape at the same time you are adding additional records to the logging buffer. Once the logging 
process has made space available in the logging buffer file, the logging process reactivates your 
process. 

When a disc file is specified, the logging process and logging buffer function differently. When the 
WRITELOG intrinsic has been called, your entries are loaded into the buffer area of the logging data 
segment. Your records are moved to your disc destination file when the buffer area is full. When the 
destination file becomes full, you receive a warning message only if you have set the mode 
parameter for no-wait. Otherwise, the WRITELOG intrinsic suspends your process and activates the 
logging process. If needed, the logging process allocates additional extents to your disc destination 
file up to the maximum that you specified in the :BUILD command and logging continues. The 
logging process then activates your process. 



You need the record formats to directly access the logging files. 

Logging R,ecord Format: 
record size = 128 words 
user area =119 words 



LOG RECORD AT OPENLOG 
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USER OR SUBSYSTEM LOG RECORD OR CONTINUATION RECORD 
2 3 4 6 7 8 9 
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LOG RECORD AT CLOSELOG 
2 3 4 __6_ 
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CRASH MARK 
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START/RESTART (From Log Operator Command) 
2 3 4 6 7 11 



rec# 



cksum 



code 



time 



date 



logid 



127 



TRAILER RECORD 



11 



rec# 



cksum 



code 



time 



date 



127 



logid 



SPACE RECORD 



rec# 



cksum 



code 



time 



127 



date 



CODE DEFINITION: 

Code = 1 Open log 

2 User/Subsystem Record 

3 Close log 

4 Header 

5 Trailer 

6 Restart 

7 Continuation of User of Subsystem Record 
9 Crash Marker 

10 End Transaction Marker 

11 Begin Transaction Marker 
Space Null Record 



NOTE 

1. The checksum algorithm uses the EXCLUSIVE OR function against a base of negative one. It 
is calculated on the entire record except the checksum word. 

2. 'PIN' is the index into the PCB table. To get an absolute PIN value, divide by 16. 

3. The space record code is 8224 (%20040) 

EFFECTIVE USE OF USER LOGGING 

Effective use of the User Logging Facility includes writing the log file and designing a recovery 
procedure. You must use the logging intrinsics in your program to write data to a logging file to be 
used for recovery. You must also program a recovery procedure that can read the log file and apply 
it to a backup copy of your data-set to recover your data. 
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The following steps are suggested as a procedure for effective use of User Logging. 

1. Select your logging identifier. You can find an explanation of the identifier in the MPE 
Commands manual. Make sure you use passwords/lockwords provided in the :GETLOG 
command if data security is necessary. Also be sure to specify the configured device class . 
name, i.e., TAPE for mag tape, SDISC for serial disc device, and CTAPE for cartridge tape I 
unit ('such'as 7911/7912). Otherwise an FOPEN failure will result. ■ 

2. Design your application and data structures. 

3 Determine what information must be logged in order to recover the data structures of your 
application. Assume you will have a back-up copy of the data structure to which you can 
apply the log file to recover. 

Place the appropriate calls to the User Logging Intrinsics in your application to log the data 
necessary for recovery. It is best to log edited and verified data by logging a full transaction 
at one time or wrapping transactions with start and completion records. 

4 Design and program your recovery procedure. Again, assume the recovery procedure will have 
a back-up copy of your application data structure to which it will apply the log file. Your 
recovery program must recognize the User Logging file record formats, (see "How User 
Logging Works") 

5 If you specify in the :GETLOG command that your logging identifier is associated with a disc 
file you must build that file making sure the file has the proper code [ ; CODE=LOG] and 
enough disc space to contain one day's output. Be generous with the disc file space. Divide 
the file into several extents, but allocate only the first extent. This minimizes the impact of a 
large file on your system. The user logging process allocates additional extents when necessary. 

6. Have the operator start the user logging process for your logging identifier (See :LOG 
Command in the MPE Console Operators Manual.) 

7. Run your application to log changes to your data sets to the User Logging file you specified in 
the rGETLOG command. 

If it becomes necessary to recover your data -sets, restore the back-up copy that you have saved and 
run the recovery procedure you wrote to reapply changes you made to the data structures. 
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SUGGESTED LOG FILE USES 

Usage of a log file, especially if many users are accessing the same user log file, starts with your 
application. Set up a log file separate from your data base log file with information which points to 
your entry. This separate log file might include the following information. 

1. User group and account names you are logged onto. This can be determined using the WHO 
intrinsic. 

2. Job/session input device number using the WHO intrinsic. This would only give a history 
however, and not help directly in recovery. 

3. Process Identification Number (PIN) of the process accessing the log file right now using the 
GETPROCID intrinsic. 

4. Date and time of opening the actual log file. This information can be accessed by the 
CALENDAR and CLOCK intrinsics. (The date and time returned by these intrinsics match the 
format of this information in the data base log file.) Put in calls to these intrinsics immediately 
after a successful OPENLOG intrinsic call. 

5. The fuMy qualified file name of the data set log file being accessed including the ASCII of the 
LOGID. 

When you need to recover the file listing, the additional file can be read and the log file opened. 
Search the log file for the LOGID and the creator that match in the OPENLOG record (type 1). 
Verify using the date and time. Use the PIN to verify the creator in case there are duplicate creators. 
Then pick up the LOG number. All records with this LOG number will be in your file. 
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ASCII 

Character 



First Character 
Octal Equivalent 



A 


040400 


B 


041000 


C 


041400 


D 


042000 


E 


042400 


F 


043000 


G 


043400 


H 


044000 


1 


044400 


J 


045000 


K 


045400 


L 


046000 


M 


046400 


N 


047000 





047400 


P 


050000 


Q 


050400 


R 


051000 


S 


051400 


T 


052000 


U 


052400 


V 


053000 


w 


053400 


X 


054000 


Y 


054400 


z 


055000 


a 


060400 


b 


061000 


c 


061400 


d 


062000 


e 


062400 


f 


063000 




063400 


h 


064000 


i 


064400 


j 


065000 


k 


065400 


1 


066000 


m 


066400 


n 


067000 





067400 


P 


070000 


q 


070400 


r 


071000 


s 


071400 


t 


072000 


u 


072400 


V 


073000 


w 


073400 


X 


074000 


y 


074400 


z 


075000 





1 

2 

3 
4 

5 
6 
7 
8 
9 

NUL 
SOH 
STX 
ETX 
EOT 
ENQ 



Second Character 
Octal Equivalent 



030000 
030400 
031000 
031400 
032000 
032400 
033000 
033400 
034000 
034400 

000000 
000400 
001000 
001400 
002000 
002400 



000101 
000102 
000103 
000104 
000105 
000106 
000107 
000110 

0001 1 1 

0001 1 2 
000113 
000114 
0001 1 5 
000116 
000117 
000120 
000121 
0001 22 
000123 
000124 
000125 

0001 26 

0001 27 
000130 
000131 
000132 

000141 
000142 
000143 
000144 
000145 
000146 
000147 
0001 50 
000151 

0001 52 

0001 53 
000154 
0001 55 

0001 56 

0001 57 
000160 
000161 
000162 
000163 
000164 
000165 
000166 
000167 
0001 70 
000171 
000172 

000060 
000061 
000062 
000063 
000064 
000065 
000066 
000067 
000070 
000071 

000000 
000001 
000002 
000003 
000004 
000005 



ASCII 

Character 



ACK 
BEL 

BS 

HT 

LF 

VT 

FF 

CR 

SO 

SI 
DLE 
DC1 
DC2 
DC3 
DC4 
NAK 
SYN 
ETB 
CAN 

EM 
SUB 
ESC 

FS 

GS 

RS 

US 
SPACE 



% 
& 



< 

> 

@ 

[ 

\ 
] 
A 



DEL 



First Character 
Octal Equivalent 



003000 

003400 

004000 

004400 

005000 

005400 

006000 

006400 

007000 

007400 

010000 

010400 

011000 

011400 

01 2000 

012400 

013000 

013400 

014000 

014400 

015000 

015400 

016000 

016400 

017000 

017400 

020000 

020400 

021000 

021400 

022000 

022400 

023000 

023400 

024000 

024400 

025000 

025400 

026000 

026400 

027000 

027400 

035000 

035400 

036000 

036400 

037000 

03 7400 

040000 

055400 

056000 

056400 

057000 

057400 

060000 

075400 

076000 

076400 

077000 

077400 



Second Character 
Octal Equivalent 



000006 

000007 

000010 

000011 

000012 

000013 

000014 

000015 

000016 

000017 

000020 

000021 

000022 

000023 

000024 

000025 

000026 

000027 

000030 

000031 

000032 

000033 

000034 

000035 

000036 

000037 

000040 

000041 

000042 

000043 

000044 

000045 

000046 

000047 

000050 

000051 

000052 

000053 

000054 

000055 

000056 

000057 

000072 

000073 

000074 

000075 

000076 

000077 

000100 

000133 

000134 

000135 

000136 

000137 

000140 

0001 73 

0001 74 

0001 75 

0001 76 

0001 77 



First Character 



Second Character 



_>^ 



i i i 

















1 2 3 


4 5 6 


7 


8 9 


10 11 12 


13 


14 


15 
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Whenever a disc file is created, MPE automatically supplies a file label in the first sector of the 
first extent occupied by that file. Such labels always appear in the format described below. (User- 
supplied labels, if present, are located in the sectors immediately following the MPE file label.) 
The contents of a label may be listed by using the :LISTF -1 command described in the MPE Com- 
mands Reference Manual. 



Words 




Contents 


0-3 




Local file name. 


4-7 




Group name. 


8-11 




Account name. 


12-15 




User name of file creator. 


16-19 




File lockword. 


20-21 




File security matrix. 


22 


(Bits 0:15) 


Not used. 




(Bit 15:1) 


File secure bit: 

If 1, file secured. 
If 0, file released. 


23 




File creation date 


24 




Last access date. 


25 




Last modification date. 


26 




File code. 


27 




File control block vector. 


28 


(Bit 0:1) 


Store Bit. (If on, :STORE 

nrnffress /) 



(Bit 1:1) 
(Bit 2:1) 

(Bit 3:1) 

(Bits 4:4) 
(Bits 8:6) 
(Bit 14:1) 
(Bit 15:1) 



Restore Bit. (If on, :RESTORE in progress.) 

Load Bit. (If on, program file is loaded.) 

Exclusive Bit. (If on, file is opened with exclusive 
access.) 

Device sub-type. 

Device type. 

File is open for write. 

File is open for read. 
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Words 
29 

30-31 
32-33 



(Bits 0:8) 
(Bits 8:8) 



Contents 

Number of user labels written. 
Number of user labels available. 

File limit in blocks. 

Private volume information (while file is open). 



34 
35 
36 
37 
38 
39 



40 
41 

42-43 

44-45 

46-107 

108-123 

124-127 



(Bits 0:8) 
(Bits 8:3) 
(Bits 11:5) 



File label check sum (used for error detection). 

Cold-load identity. 

Foptions specifications. 

Logical record size (in negative bytes). 

Block size (in words). 

Sector offset to data. 

Not used. 

Number of extents-1. 

Last extent size in sectors. 

Extent size in sectors. 

Number of logical records in file. 

First extent descriptor. 

Remaining extent descriptors (32 maximum). 

Not used. 

Device class name. 



Note 



An extent descriptor (words 44 through 107 above) is a double word. 
The first byte contains the volume table index of the volume in which 
the extent resides; the remaining three bytes of the double word 
extent descriptor contain the first sector number of the extent. 
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END-OF-FILE INDICATION 



APPENDIX 



The end-of-file indication will be returned by the card reader and tape drivers under conditions 
specified by the initiators of read requests. The type of requests are as follows: 

Type Class of end-of-file 

A All records that begin with a colon ( :). 

B All records that contain, starting in the first byte, :EOD, 

:EOJ, :JOB and :DATA (See Note.) 

E Hardware-sensed end-of-file. 



NOTE: If the word count is less than 3 or the byte count is less 
than 6, then Type B reads are converted to Type A reads. 



In utilizing the card/tape devices as files via the file system, the following types are assigned: 

File Specified Type 

$STDIN Type A. 

$STDINX Type B. 

Dev=CARD/TAPE Type B, if device job/data accepting. 

Type E, if device not job/data accepting. 



_i _ jy czi - j:j-1 *ii i 



Any suDsequent requests lnmaiea Dy tne ariver ionowing sensing oi an enu-oi-uie cunuiuun win ue 
rejected with an end-of-file indication. 

When reading from an unlabeled tape file, the request encountering a tape mark will respond with 
an end-of-file indication but succeeding requests will be allowed to continue to read data past the 
tape mark. Under these conditions, it is the responsibility of the caller to protect against the 
occurrence of data beyond an end-of-file and to prevent reading off the end of the reel. 
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MAGNETIC TAPE LABELS 



APPENDIX 



Labels conforming to ANSI-standard can be read and written on magnetic tape files by MPE. IBM- 
standard labels can be read, but cannot be written by MPE. 

The tape labels written by MPE consist of: 



Volume Header 
File Header 1 
File Header 2 
End-of-File 1 
End-of-File 2 
End-of-Volume 1 
End-of -Volume 2 



At the beginning of each reel of tape. 

At the beginning of each file on the reel. 

Following File Header 1. 

At the end of each file on the reel. 

Following End-of-File 1. 

At the end of a reel if the tape spans more than one volume. 

Following End-of-Volume 1. 



The file labels (file headers, end-of-file, and end-of-volume labels) are written on tape using the 
:FILE command or the FOPEN intrinsic. Each label is 80 bytes long and is formatted as shown in 
Figure D-l and Table D-l. 

User-supplied labels, if any, are located on the tape as shown in Figure D-l. User-supplied labels can 
only be written on tape labeled with MPE tape labels, and the user labels must be exactly 80 bytes, 
to conform to the MPE labels. 
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II 






) 
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D 


H 
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RECORD 
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1 
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1 
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L 
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1 


2 
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RECORD 



RECORD 
1 



MULTIPLE FILES ON A SINGLE VOLUME 



J 






E 


E 










RECORD 


T 








U 

T 
L 


T 


T 


^ 


n 


M 


F 
1 


F 
2 


M 


M 



VOLUME 1 OF 3 



VOLUME 2 OF 3 



FILE A 



V 


H 


H 








( 





D 


D 


U 
H 


T 


RECORD 




I 


R 


R 


M 


1 


j 


1 


1 


2 


L 




(FILE A) 


C 



V 


H 


H 






FIRST 


/ 





D 


D 




T 


RECORD 


/ 


L 


R 


R 




M 


ON THIS 


( 


1 


1 


2 






REEL 
(FILEB) 


\ 



RECORD 

n 



FILEB 



FILE B 



RECORD 
1 



CONTINUATION OF 
FILE B 




Note: When the file spans 
more than one volume, EOV 
is written instead of EOF. 
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VOLUME 3 OF 3 
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FILEC 
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H 
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E 
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T 
M 


D 
R 
1 


D 
R 
2 


U 
H 

L 
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n 
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MULTIPLE FILES ON MULTIPLE VOLUMES 



Figure D-l. MPE Tape Labels (Conforming to ANSI-Standard) 



Table D-l. Format of Header Tape Labels Written by MPE. (ANSI Standard) 



VOLUME HEADER LABEL (80 BYTES) 



POSITION 



Bytes 1-4 

Bytes 5-10 

Bytes 1 1 -37 
Bytes 38-51 

Bytes 52-79 
Byte 80 



Bytes 1-4 
Bytes 5-21 
Bytes 22-27 

Bytes 28-31 

Bytes 32-35 

Bytes 36-41 

Bytes 42-47 
Bytes 48-53 
Byte 54 
Bytes 55-60 
Bytes 61 -73 
Bytes 74-80 



CONTENTS 



VOL/7 

volume id 

Blanks 
Blanks 

Blanks 



COMMENTS 



Indicates volume label (n specifies the relative position of this label 
within the VOL type labels. WIPE always uses 1.) Appears on each 
label. 

Six-character identifier as supplied by :FILE command, FOPEN 
intrinsic, or console operator. 

Reserved for future use. 

Not written by MPE. (Used for owner identification in ANSI- 
standard labels.). 

Reserved for future use. 

Indicates that label conforms to ANSI -standard. 



HDR1 

filename, groupname 
volume set id 

reel number 

file sequence number 

Blanks 

file creation date 

file expiration date 

%230 

Blanks 

"HP MPE 3000 

Blanks 



FILE HEADER LABEL 1 



Indicates file header 1 label. Appears before each file on the reel. 

Used for file identifier in ANSI -standard labels. 

Six -character identifier of the first volume in a set, as supplied by 
:FILE command, FOPEN intrinsic, or console operator. 

A four-digit entry from 0001 to 9999, indicating the relative posi- 
tion of a reel in a volume set. 

A four-digit entry from 0001 to 9999, indicating the relative posi- 
tion of a file on a reel . 

Not written by MPE. (Reserved for generating data groups in ANSI- 
standard labels.) 

Indicates date on which file is written to magnetic tape. 

Indicates date after which file can be overwritten. 

Indicates that file was created by MPE and the file has a lockword. 

Reserved for future use. 

System coue 

Reserved for future use. 



DEC 1981 



D-3 



Table D-l. Format of Header Tape Labels Written by MPE. (ANSI Standard) Continued 



FILE HEADER LABEL 2 



POSITION 


CONTENTS 


COMMENTS 


Bytes 1 -4 


HDR2 


Indicates header 2 label . Appears after header 1 . 


Byte 5 


record format 


"F"= Fixed 
"V" = Variable 
"U"= Undefined 


Bytes 6-10 


block length 


A five-digit entry, indicating block length in bytes. 


Bytes 11-15 


record length 


A five-digit entry, indicating record length in bytes. 


Bytes 16-23 


lockword 


MPE file lockword. 


Bytes 24-36 


Blanks 


Reserved for future use. 


Byte 37 


record type 


"A" = ASCII 
"B"= Binary 


Byte 38 


carriage control 


"C" if control 
" " if no control 


Bytes 39-80 


Blanks 

____ 


Reserved for future use. 
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WIPE DIAGNOSTIC MESSAGES 



APPENDIX 



Programs running under MPE at any batch input device or terminal may return the following types 
of error messages: 

• Command Interpreter Error Messages, reporting fatal errors that occur during the inter- 
pretation or execution of an MPE command. See the MPE Commands Reference Manual 
for a listing of these messages. 

• Command Interpreter Warning Messages, reporting unusual conditions that occur during 
command interpretation or execution but that may not necessarily be detrimental to the 
processing of the job or session. See the MPE Commands Reference Manual for a listing of 
these messages. 

• Run-Time Messages, denoting conditions that abort the running program, provided that an 
appropriate error trap has not been enabled. 

• User Messages, which are messages sent to you by other users currently running jobs or 
sessions. 

• Operator Messages, which are messages sent to yqu by the console operator. 

• System Messages, which denote miscellaneous conditions that terminate or otherwise 
affect the job/session, such as an abort requested by the system supervisor or console 
operator. 

Other messages may be received only at the system console. These are: 

Console Operator Messages, including: 

• Status Messages that indicate the current status of jobs/sessions or input/output 
devices. 

• Input/Output Messages that request service for, and report errors on, input/ 
output devices. 

• User Messages, sent by users to the console operator. 
System Failure Messages, including: 

• System Failure Messages. 

• Cold Load Error Messages. 
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RUN-TIME MESSAGES 

Your program can be aborted as a result of any of the following general types of run-time errors: 

— Special violations — those detected through the internal interrupt structure (such as arithmetic 
trap errors, parity errors, bounds violations, etc.) and other violations detected by MPE (such 
as stack overflows or invalid stack markers). These are PROGRAM ERRORS and are described 
in a following table. 

— Explicit calls to the QUIT intrinsic. 

— Explicit calls to the QUITROG intrinsic. 

— Violations of other callable intrinsics, such as passing of illegal parameters or the invoking of an 
intrinsic without having the required capability class or a valid register environment. (These are 
listed in the RUN-TIME error table. The intrinsics are listed in the INTRINSIC table, and errors 
encountered by them are listed in tables by specific intrinsic: FILESYSTEM, LOADER 
CREATE, ACTIVATE, SUSPEND, MYCOMMAND and LOCKGLORIN. 

If an appropriate error trap has been armed, control transfers to the trap procedure which may 
attempt recovery or take some other action. But if no trap has been armed for the type of error 
encountered, MPE terminates the user's process and transmits a run-time (abort) message to the 
user's output device. In a multi-process structure, QUIT aborts only the violating process but all 
other errors abort the entire program. 

If the aborted program was running in a batch job, the job is removed from the system (if no 
:CONTINUE command overrides termination). 

If it was running in a session, control of the session is returned to you at the terminal. 

NOTE 

An abort-error will occur if a user process invokes certain 
callable intrinsics when the DB register is not pointing to its 
normal position (e.g. DB is pointing at an extra data segment). 
If this happens and a user trap procedure is invoked, the DB 
register is reset to the normal position before the trap 
procedure is entered. 

The format for run-time errors is: 
ABORT:pname.segment.location:sname.segment.location 



p-field s-field 

<msgtype>#<msgno> : < message > [.PARAM /" 1 < number > ] 



m-field (from 1 to 7 lines) 
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where: 
p-field 

s-field 



is the last location of the last instruction executed in the user program 
prior to the abort. 

is output only if the abort occurred when executing code belonging to 
a library segment referenced by the user program. The field provides 
the instruction location within the library segment that initiated the 
abort. 



Within the p-field and s-field, the parameters are: 



pname 



sname 



segment 



location 



The name of the program file containing the user's program and 
optionally, the group and account name. 

In the special case of a process having been PROCREATED from a 
segment in a segmented library (SL) (for example, the Command 
Interpreter), an asterisk (*) is output followed by the SL name in 
symbolic form (sname, below). 

The symbolic name of the SL in which the segment exists 

SYSL — System SL 
PUSL - Public SL 
GRSL - Group SL 

The logical number of the code segment relating to either the program 
or SL, whichever is appropriate. 

The location in the code segment. This is expressed in terms of the 
displacement (P-PB), where P is the absolute address of the instruction 
and PB the absolute address of the base of the code segment. 

NOTE 

Octal numbers are indicated by a percent sign (%) preceding 
the number. 

If the stack is completely destroyed and no valid stack 
markers can be found that define a user environment, then 
the above-defined subfields will be output containing a 
question mark (?). 
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m-field 



<msgno> 

< message > 

< number > 



contains the error message text. 

The parameters within the m-field are 

<msgtype> is one of: 

PROGRAM ERROR 
ERROR: INTRINSIC 
RUN-TIME ERROR 
FILESYSTEM ERROR 
LOADER ERROR 
CREATE ERROR 
ACTIVATE ERROR 
SUSPEND ERROR 
MYCOMMAND ERROR 
LOCKGLORIN ERROR 

and corresponds to the names of the following tables. 

is a message number, which is an index into the < msgtype > table. 

is the text of the message which can be found along with the message 
number in the message type table. 

is the number of the invalid parameter passed to an intrinsic (the 
message will read: PARAM # < number »or is the parameter passed to 
the QUIT or QUITPROG intrinsic (the message will read: PARAM =) 



Some examples of run-time messages are: 
Examples: 

ABORT :BIN.ED.MPE.%0.%12 

ERROR: INTRINSIC #62: BINARY 

RUN-TIME ERROR #5: PARAMETER ADDRESS VIOLATION. PARAM #1 

BINARY was called with an invalid byte address. 

ABORT :OV.ED.MPE.%0.%177777 
PROGRAM ERROR #20: STACK OVERFLOW 

The program was in an infinite loop doing a DUP instruction. 

ABORT :PRIV.ED.MPE.%0.%3 

PROGRAM ERROR #6: PRIVILEGED INSTRUCTION 

A return was made from a non-privileged segment to a privileged segment. 
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ABORT :QUIT.ED.MPE.%0.%1 

PROGRAM ERROR #18; PROCESS QUIT .P ARAM = 15 

The program called QUIT Intrinsic with a parameter of 15. 

ABORT :UF.ED.MPE.%0.%1 

PROGRAM ERROR #29: STACK UNDERFLOW 

The program was in an infinite loop doing a DEL instruction. 

ABORT :EDITOR.PUB.SYS.%2.%7 

ERROR: INTRINSIC #100: CREATE 

CREATE ERROR #30: LOAD ERROR 

LOADER ERROR #65: UNABLE TO OBTAIN CST ENTRIES 



Nearly all CST entries were ALLOCATEd and the program tried to create a process which required 
more CST's than were available. 

ABORT :EDITOR.PUB,SYS.%2.%13 

ERROR: INTRINSIC #104: ACTIVATE 

ACTIVATE ERROR #21: ACTIVATION OF MAIN PROCESS NOT ALLOWED 

The program tried to activate a non-existent process. 

The following is a list of < msgtype > tables, the message number and text for each message found 
for each type of message: 



Table E-l. Program Error Messages 



MESSAGE 
NO. 



1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 

17 



MESSAGE 



INTEGER OVERFLOW 

FLOATING POINT OVERFLOW 

FLOATING POINT UNDERFLOW 

INTEGER DIVIDE BY ZERO 

FLOATING POINT DIVIDE BY ZERO 

PRIVILEGED INSTRUCTION 

ILLEGAL INSTRUCTION 

EXTENDED PRECISION OVERFLOW 

EXTENDED PRECISION UNDERFLOW 

EXTENDED PRECISION DIVIDE BY ZERO 

DECIMAL OVERFLOW 

INVALID ASCII DIGIT 

INVALID DECIMAL DIGIT 

INVALID WORD COUNT 

INVALID DECIMAL OPERAND LENGTH 

DECIMAL DIVIDE BY ZERO 

STTUNCALLABLE 



LOGIC ERROR IN THE PROGRAM. 
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Table E-l. Program Error Messages (Continued) 



PROCESS QU\T=<number> 
PROGRAM QUlT=<number> 



STACK OVERFLOW 



PROGRAM KILLED 

INVALID STACK MARKER 
ADDRESS VIOLATION 
BOUNDS VIOLATION 



NON-RESPONDING MODULE 
DATA PARITY 
MEMORY PARITY 
SYSTEM PARITY 

STACK UNDERFLOW 
CST VIOLATION 
STT VIOLATION 



MESSAGE 



<number> is the value passed to the QUITPROG or 
QUIT intrinsic by the terminating process. (This 
value is output only if it is not zero.) 

( Logic error in the program. Probably looping and 
| adding to the stack. May require larger MAXDATA 
y when preparing program. 

Program aborted from an external source. 



Possible logic error in program. 



Possible hardware problem. 



Logic error in program. Probably Invalid CST or STT 
discovered by hardware. Explicit PCAL from TOS 
may have referenced non-existent CST or STT. May 
be bad program file. 



Table E-2. Intrinsic Error Numbers 



MESSAGE 
NO. 



1 

2 

3 

4 

5 

6 

7 

8 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 



INTRINSIC 



FOPEN 

FREAD 

FWRITE 

FUPDATE 

FSPACE 

FPOINT 

FREADDIR 

FCLOSE 

FCHECK 

FGETINFO 

FREADSEEK 

FCONTROL 

FSETMODE 

FLOCK 

FUNLOCK 

FRENAME 

FRELATE 

FREADLABEL 



MESSAGE 
NO. 



20 

21 

22 

30 

31 

32 

33 

34 

35 

36 

40 

42 

43 

44 

45 

50 

51 

52 

53 



INTRINSIC 



FWRITELABEL 

PRINTFILEINFO 

IOWAIT 

GETLOCRIN 

FREELOCRIN 

LOCKLOCRIN 

UNLOCKLOCRIN 

LOCKGLORIN 

UNLOCKGLORIN 

LOCRINOWNER 

TIMER 

PROCTIME 

CALENDAR 

CLOCK 

PAUSE 

XARITRAP 

ARITRAP 

XLIBTRAP 

XSYSTRAP 
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MESSAGE 
NO. 

54 

55 

56 

60 

61 

62 

63 

64 

65 

66 

67 

68 

69 

70 

71 

72 

73 

74 

75 

76 

77 

78 

79 

80 

81 

82 

83 



INTRINSIC 



XCONTRAP 

RESETCONTROL 

CAUSEBREAK 

TERMINATE 

CTRANSLATE 

BINARY 

ASCII 

READ 

PRINT 

PRINTOP 

PRINTOREPLY 

COMMAND 

WHO 

SEARCH 

MYCOMMAND 

SETJCW 

GETJCW 

DBINARY 

D ASCI I 

QUIT 

STACKDUMP 

SETDUMP 

RESETDUMP 

LOADPROC 

UNLOADPROC 

INITUSLF 

ADJUSTSLF 



MESSAGE 
NO. 



84 

99 

100 

102 

103 

104 

105 

106 

107 

108 

109 

110 

112 

120 

130 

131 

132 

133 

134 

135 

136 

139 

191 

200 

201 

210 

211 

212 

307 



INTRINSIC 



EXPANDUSLF 

DEBUG 

CREATE 

KILL 

SUSPEND 

ACTIVATE 

GETORIGIN 

MAIL 

SENDMAIL 

RECEIVEMAIL 

FATHER 

GETPROCINFO 

GETPROCID 

GETPRIORITY 

GETDSEG 

FREEDSEG 

DMOVIN 

DMOVEOUT 

ALTDSEG 

DLSIZE 

ZSIZE 

SWITCHDB 

PTAPE 

GETPRiVMODE 

GETUSERMODE 

OPEN LOG 

WRITELOG 

CLOSELOG 

FERRMSG 



Table E-3. Run-Time Error Messages 



MESSAGE 
NO. 



1 
2 
3 
4 
5 
6 
7 
8 
9 



MESSAGE 



ILLEGAL DB REGISTER 
ILLEGAL CAPABILITY 
OMITTED PARAMETER 
INCORRECT S REGISTER 
PARAMETER ADDRESS VIOLATION 
PARAMETER END ADDRESS VIOLATION 
ILLEGAL PARAMETER 
PARAMETER VALUE INVALID 
INCORRECT Q REGISTER 



Run-time errors are discovered by MPE performing parameter checking before attempting certain operations. 
These errors are caused by a logic error in the program. 
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Table E-4.. File System Error Messages 



END OF FILE(FSERRO) 

ILLEGAL DB REGISTER SETTING (FSERR 1) 

ILLEGAL CAPABILITY (FSERR 2) 

ILLEGAL PARAMETER VALUE (FSERR 8) 

INVALID RECORD SIZE SPECIFICATION (FSERR 10} 

INVALID RESULTANT BLOCK SIZE (FSERR 11 ) 

RECORD NUMBER OUT OF RANGE (FSERR 12) 

INVALID OPERATION (FSERR 20) 

DATA PARITY ERROR (FSERR 21) 

SOFTWARE TIME-OUT (FSERR 22) 

END OF TAPE (FSERR 23) 

UNIT NOT READY (FSERR 24) 

NOWRITE-RINGONTAPE (FSERR 25) 

TRANSMISSION ERROR (FSERR 26) 

I/O TIME-OUT (FSERR 27 

TIMING ERROR OR DATA OVERRUN (FSERR 28) 

SIO FAILURE (FSERR 29) 

UNIT FAILURE (FSERR 30) 

END OF LINE (FSERR 31) 
SOFTWARE ABORT (FSERR 32) 

DATA LOST (FSERR 33) 

UNIT NOT ON-LINE (FSERR 34) 

DATA-SET NOT READY (FSERR 35) 

INVALID DISC ADDRESS (FSERR 36) 

INVALID MEMORY ADDRESS (FSERR 37) 

TAPE PARITY ERROR (FSERR 38) 

RECOVERED TAPE ERROR (FSERR 39) 

OPERATION INCONSISTENT WITH ACCESS TYPE (FSERR 40) 

OPERATION INCONSISTENT WITH RECORD TYPE (FSERR 41) 

OPERATION INCONSISTENT WITH DEVICE TYPE (FSERR 42) 

WRITE EXCEEDS RECORD SIZE (FSERR 43) 

UPDATE AT RECORD ZERO (FSERR 44) 

PRIVILEGED FILE VIOLATION (FSERR 45) 

OUT OF DISC SPACE (FSERR 46) 

I/O ERROR ON FILE LABEL (FSERR 47) 

INVALID OPERATION DUE TO MULTIPLE FILE ACCESS (FSERR 48) 

UNIMPLEMENTED FUNCTION (FSERR 49) 

NONEXISTENT ACCOUNT (FSERR 50) 

NONEXISTENT GROUP (FSERR 51) 

NONEXISTENT PERMANENT FILE (FSERR 52) 

NONEXISTENT TEMPORARY FILE (FSERR 53) 

INVALID FILE REFERENCE (FSERR 54) 

DEVICE UNAVAILABLE (FSERR 55) 

INVALID DEVICE SPECIFICATION (FSERR 56) 

OUT OF VIRTUAL MEMORY (FSERR 57) 

NO PASSED FILE (FSERR 58) 

STANDARD LABEL VIOLATION (FSERR 59) 

GLOBAL RIN UNAVAILABLE (FSERR 60) 

OUT OF GROUP DISC SPACE (FSERR 61) 

OUT OF ACCOUNT DISC SPACE (FSERR 62) 

USER LACKS NON-SHARABLE DEVICE CAPABILITY (FSERR 63) 

USER LACKS MULTI-RIN CAPABILITY (FSERR 64) 

PUNCH HOPPER EMPTY (FSERR 65) 

PLOTTER LIMIT SWITCH REACHED (FSERR 66) 
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Table E-4. File System Error Messages (Continued) 



PAPER TAPE ERROR (FSERR 67) 

INSUFFICIENT SYSTEM RESOURCES (FSERR 68) 

I/O ERROR (FSERR 69) 

TOO MANY FILES OPEN (FSERR 71) 

INVALID FILE NUMBER (FSERR 72) 

BOUNDS VIOLATION (FSERR 73) 

NO-WAIT I/O PENDING (FSERR 77) 

NO NO-WAIT I/O PENDING FOR ANY FILE (FSERR 78) 

NO NO-WAIT I/O PENDING FOR SPECIAL FILE (FSERR 79) 

SPOOFLE SIZE EXCEEDS CONFIGURATION (FSERR 80) 

NO "SPOOL" CLASS IN SYSTEM (FSERR 81) 

INSUFFICIENT SPACE FOR SPOOFLE (FSERR 82) 

I/O ERROR ON SPOOFLE (FSERR 83) 

DEVICE UNAVAILABLE FOR SPOOFLE (FSERR 84) 

OPERATION INCONSISTENT WITH SPOOLING (FSERR 85) 

NONEXISTENT SPOOFLE (FSERR 86) 

BAD SPOOFLE BLOCK (FSERR 87) 
SPOOLING ERROR (FSERR 88) 

POWER FAILURE (FSERR 89) 

EXCLUSIVE VIOLATION: FILE BEING ACCESSED (FSERR 90) 

EXCLUSIVE VIOLATION: FILE ACCESSED EXCLUSIVELY (FSERR 91) 

LOCKWORD VIOLATION (FSERR 92) 

SECURITY VIOLATION (FSERR 93) 

USER IS NOT CREATOR (FSERR 94} 

READ COMPLETED DUE TO BREAK (FSERR 95) 

DISC I/O ERROR (FSERR 96) 

NO CONTROL Y PIN (FSERR 97) 

READ TIME OVERFLOW (FSERR 98) 

BOT AND BACKSPACE TAPE (FSERR 99) 

DUPLICATE PERMANENT FILE NAME (FSERR 100) 

DUPLICATE TEMPORARY FILE NAME (FSERR 101) 

I/O ERROR ON DIRECTORY (FSERR 102) 

PERMANENT FILE DIRECTORY OVERFLOW (FSERR 103) 

TEMPORARY FILE DIRECTORY OVERFLOW (FSERR 104) 

BAD VARIABLE BLOCK STRUCTURE (FSERR 105) 

EXTENT SIZE EXCEEDS MAXIMUM (FSERR 106) 

INSUFFICIENT SPACE FOR USER LABELS (FSERR 107) 

INVALID FILE LABEL (FSERR 108) 

INVALID CARRIAGE CONTROL (FSERR 109) 

ATTEMPT TO SAVE PERMANENT FILE AS TEMPORARY (FSERR 1 10) 

USER LACKS SAVE FILES (SF) CAPABILITY (FSERR 111) 

USER LACKS PRIVATE VOLUMES (UV) CAPABILITY (FSERR 112) 

VOLUME SET NOT MOUNTED - MOUNT PROBLEM (FSERR 1 13) 

VOLUME SET NOT DISMOUNTED - DISMOUNT PROBLEM (FSERR 1 14) 

ATTEMPTED RENAME ACROSS VOLUME SETS - REJECTED (FSERR 115) 
INVALID TAPE LABEL FOPEN PARAMETERS (FSERR 1 16) 

ATTEMPTTO WRITE ON AN UNEXPIRED TAPE FILE (FSERR 167) 

INVALID HEADER OR TRAILER TAPE LABEL (FSERR 118) 

I/O ERROR POSITIONING TAPE FOR TAPE LABELS (FSERR 119) 

ATTEMPT TO WRITE IBM STANDARD TAPE LABEL (FSERR 120) 

-r- A p£ LABEL LOCKWORD VIOLATION (FSERR 121) 

END OF TAPE VOLUME SET (FSERR 123) 

INACTIVE RIO RECORD ACCESSED (FSERR 148) 

MISSING ITEMNUM OR ITEMVALUE (149) 
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INVALID ITEMNUM VALUE (150) 



Table E-4. File System Error Messages (Continued) 



THE RECORD IS MARKED DELETED. FPOINT POSITIONED POINTER TO A RECORD THAT WAS 
MARKED FOR DELETION (FSERR 170) 

DUPLICATE KEY VALUE (FSERR 171) 

NO SUCH KEY (FSERR 172) 

TCOUNT PARAMETER LARGER THAN RECORD SIZE (FSERR 173) 

CAN NOT GET EXTRA DATA SEGMENT (FSERR 174) 

KSAM INTERNAL ERROR (FSERR 175) 

ILLEGAL EXTRA DATA SEGMENT LENGTH (FSERR 176) 

TOO MANY EXTRA DATA SEGMENTS FOR THIS PROCESS (FSERR 177) 

EXTRA DATA SEGMENT TOO SMALL (FSERR 178) 

THE FILE MUST BE LOCKED BEFORE ISSUING THIS INTRINSIC (FSERR 179) 

THE KSAM FILE MUST BE REBUILT BECAUSE THIS VERSION OF KSAM DOES NOT HANDLE THE 
FILE BUILT BY PREVIOUS VERSION (FSERR 180) 

INVALID KEY STARTING POSITION (FSERR 181) 

FILE IS EMPTY (FSERR 182) 

RECORD DOES NOT CONTAIN ALL KEYS (FSERR 183) 

INVALID RECORD NUMBER (FFINDN INTRINSIC) (FSERR 183) 

SEQUENCE ERROR IN PRIMARY KEY (FSERR 185) 

INVALID KEY LENGTH - NUMERIC DISPLAY OR PACKED DECIMAL (FSERR 186) 

INVALID KEY SPECIFICATION (FSERR 187) 

INVALID DEVICE SPECIFICATION (FSERR 188) 

INVALID RECORD FORMAT (FSERR 189) 

INVALID KEY BLOCKING FACTOR VALUE (FSERR 190) 

RECORD DOES NOT CONTAIN SEARCH KEY FOR DELETION. SPECIFIED KEY VALUE POINTS TO 
RECORD WHICH DOES NOT CONTAIN THAT VALUE. (FSERR 191) 

SYSTEM FAILURE OCCURRED WHILE KSAM FILE WAS OPENED (FSERR 192) 

INVALID ID SEQUENCE (FSERR 201) 

INVALID TELEPHONE NUMBER (FSERR 202) 

NO TELEPHONE LIST SPECIFIED (FSERR 203) 

INVALID ID SEQUENCE (FSERR 201) 

INVALID TELEPHONE NUMBER (FSERR 202) 

NO TELEPHONE LIST SPECIFIED (FSERR 203) 

UNABLE TO ALLOCATE AN EXTRA DATA SEGMENT FOR DS/3000. (DSERR 204) 

UNABLE TO EXPAND THE DS/3000 EXTRA DATA SEGMENT. (DSERR 205) 

FILE NUMBER RETURNED FROM IOWAIT IS NOT A DS LINE NUMBER (DSWARN 212) 

THE REQUESTED DS LINE HAS NOT BEEN OPEN WITH A USER rDSLINE COMMAND (DSERR 214) 

MESSAGE REJECTED BY THE REMOTE COMPUTER. (DSERR 216) 

INSUFFICIENT AMOUNT OF USER STACK AVAILABLE. (DSERR 217) 

INVALID DS MESSAGE FORMAT. (INTERNAL DS ERROR) (DSERR 221) 

THE LOCAL COMMUNICATION LINE HAS NOT BEEN OPENED BY THE OPERATOR (DSERR 240) 

THE DS LINE IS IN USE EXCLUSIVELY OR BY ANOTHER SUBSYSTEM (DSERR 241) 

INTERNAL DS SOFTWARE MALFUNCTION. (DSERR 242) 

THE REMOTE COMPUTER IS NOT RESPONDING. (DSERR 243) 

COMMUNICATIONS INTERFACE ERROR. THE REMOTE COMPUTER RESET THE LINE (DSERR 244) 

COMMUNICATIONS INTERFACE ERROR. RECEIVE TIMEOUT. (DSERR 245) 

COMMUNICATIONS INTERFACE ERROR. REMOTE HAS DISCONNECTED (DSERR 246) 

COMMUNICATIONS INTERFACE ERROR. LOCAL TIME OUT (DSERR 247) 

COMMUNICATIONS INTERFACE ERROR. CONNECT TIME OUT (DSERR 248) 

COMMUNICATIONS INTERFACE ERROR. REMOTE REJECTED CONNECTION (DSERR 249) 

COMMUNICATIONS INTERFACE ERROR. CARRIER LOST. (DSERR 250) 

COMMUNICATIONS INTERFACE ERROR. THE LOCAL DATA SET FOR THE DS LINE WHEN NOT 
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Table E-4.. File System Error Messages (Continued) 



COMMUNICATIONS INTERFACE ERROR. HARDWARE FAILURE. (DSERR 252) 

COMMUNICATIONS INTERFACE ERROR. NEGATIVE RESPONSE TO THE DIAL REQUEST BY THE 

OPERATOR. (DSERR 253) 
COMMUNICATIONS INTERFACE ERROR. INVALID I/O CONFIGURATION. (DSERR 254) 
COMMUNICATIONS INTERFACE ERROR. UNANTICIPATED ERROR CONDITION. (DSERR 255) 
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Table E-5. Loader Error and Warning Messages 



ILLEGAL LIBRARY SEARCH (LOAD ERR 20) 

UNKNOWN ENTRY POINT (LOAD ERR 21) 

TRACE SUBSYSTEM NOT PRESENT (LOAD ERR 22) 

STACK SIZE TOO SMALL (LOAD ERR 23) 

MAXDATA TOO LARGE (LOAD ERR 24) 

DATA SEGMENT TOO LARGE (LOAD ERR 25) 

PROGRAM LOADED IN OPPOSITE MODE (LOAD ERR 26) 

SL BINDING ERROR (LOAD ERR 27) 

INVALID SYSTEM SL FILE (LOAD ERR 28) 

INVALID PUBLIC SL FILE (LOAD ERR 29) 

INVALID GROUP SL FILE (LOAD ERR 30) 

INVALID PROGRAM FILE (LOAD ERR 31) 

INVALID LIST FILE (LOAD ERR 32) 

CODE SEGMENT TOO LARGE (LOAD ERR 33) 

PROGRAM USES MORE THAN ONE EXTENT (LOAD ERR 34) 

DATA SEGMENT TOO LARGE (LOAD ERR 35) 

DATA SEGMENT TOO LARGE (LOAD ERR 36) 

TOO MANY CODE SEGMENTS (LOAD ERR 37) 

TOO MANY CODE SEGMENTS (LOAD ERR 38) 

ILLEGAL CAPABILITY (LOAD ERR 39) 

TOO MANY PROCEDURES LOADED (LOAD ERR 40) 

UNKNOWN PROCEDURE NAME (LOAD ERR 41) 

INVALID PROCEDURE NUMBER (LOAD ERR 42) 

ILLEGAL PROCEDURE UNLOAD (LOAD ERR 43) 

ILLEGAL SL CAPABILITY (LOAD ERR 44) 

INVALID ENTRY POINT (LOAD ERR 45) 

UNABLE TO OPEN SYSTEM SL FILE (LOAD ERR 50) 

UNABLE TO OPEN PUBLIC SL FILE (LOAD ERR 51) 

UNABLE TO OPEN GROUP SL FILE (LOAD ERR 52) 

UNABLE TO OPEN PROGRAM FILE (LOAD ERR 53) 

UNABLE TO OPEN LIST FILE (LOAD ERR 54) 

UNABLE TO CLOSE SYSTEM SL FILE (LOAD ERR 55) 

UNABLE TO CLOSE PUBLIC SL FILE (LOAD ERR 56) 

UNABLE TO CLOSE GROUP SL FILE (LOAD ERR 57) 

UNABLE TO CLOSE PROGRAM FILE (LOAD ERR 58) 

UNABLE TO CLOSE LIST FILE (LOAD ERR 59) 

EOF OR I/O ERROR ON SYSTEM SL FILE (LOAD ERR 60) 

EOF OR I/O ERROR ON PUBLICSL FILE (LOAD ERR 61) 

EOF OR I/O ERROR ON GROUP SL FILE (LOAD ERR 62) 

EOF OR I/O ERROR ON PROGRAM FILE (LOAD ERR 63) 

EOF OR I/O ERROR ON LIST FILE (LOAD ERR 64) 

UNABLE TO OBTAIN CST ENTRIES (LOAD ERR 65) 

UNABLE TO OBTAIN PROCESS DST ENTRY (LOAD ERR 66) 

UNABLE TO OBTAIN MAIL DATA SEGMENT (LOAD ERR 67) 

UNABLE TO CREATE LOAD PROCESS (LOAD ERR 68) 

SEGMENT TABLE OVERFLOW (LOAD ERR 70) 

UNABLE TO OBTAIN SUFFICIENT DL STORAGE (LOAD ERR 71) 

ATTIO ERROR (LOAD ERR 72) 

UNABLE TO OBTAIN VIRTUAL MEMORY (LOAD ERR 73) 

DIRECTORY I/O ERROR (LOAD ERR 74) 

PRINT I/O ERROR (LOAD ERR 75) 

ILLEGAL DLSIZE (LOAD ERR 76) 

PROGRAM ALREADY ALLOCATED (LOAD ERR 80) 

ILLEGAL PROGRAM ALLOCATION (LOAD ERR 81) 

PROGRAM NOT ALLOCATED (LOAD ERR 82) 
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Table E-5. Loader Error and Warning Messages (Continued) 



ILLEGAL PROGRAM DEALLOCATION (LOAD ERR 83) 
PROCEDURE ALREADY ALLOCATED (LOAD ERR 84) 
ILLEGAL PROCEDURE ALLOCATION (LOAD ERR 85) 
PROCEDURE NOT ALLOCATED (LOAD ERR 86) 
ILLEGAL PROCEDURE DEALLOCATION (LOAD ERR 87) 
LMAP NOT AVAILABLE (LOAD WARN 88) 
PROGRAM LOADED WITH LIB=nnn (LOAD WARN 89) 



Table E-6. CREATE Intrinsic Errors 



UNKNOWN SUBQUEUE NAME (CREATE ERROR 20) 

SUBQUEUE 'A' REQUESTED WITHOUT FROZEN STACK (CREATE ERROR 21 ) 

INSUFFICIENT CAPABILITY FOR NON-STANDARD SUBQUEUE (CREATE ERROR 23) 

UNKNOWN PORTION OF MASTER QUEUE (CREATE ERROR 24) 

INSUFFICIENT CAPABILITY FOR MASTER QUEUE (CREATE ERROR 25) 

ABSOLUTE PRIORITY REQUESTED WITHOUT CAPABILITY (CREATE ERROR 26) 

ILLEGAL PRIORITY CLASS SPECIFIED (CREATE ERROR 27) 

PRIORITY OMITTED WHILE FATHER PROCESS IN MASTER QUEUE. (CREATE ERR 28) 

PRIORITY RANK RESERVED TO SUPERVISOR CAPABILITY (CREATE ERROR 29) 

LOAD ERROR (CREATE ERROR 30) 

LACK OF SYSTEM RESOURCE (CREATE ERROR 31) 

MAXIMUM ACCOUNT PRIORITY EXCEEDED (CREATE ERROR 32) 



Table E-7. ACTIVATE Intrinsic Errors 



ACTIVATION OF SYSTEM PROCESS NOT ALLOWED (ACTIVATE ERROR 20) 
ACTIVATION OF MAIN PROCESS NOT ALLOWED (ACTIVATE ERROR 21) 



Table E-8. SUSPEND Intrinsic Error 



INSUFFICIENT CAPABILITY (SUSPEND ERROR 20) 



Table E-9. MYCOMMAND Intrinsic Error 



PARSED PAR AM OF COM IMAGE > 255 CHARACTERS 



Table E-10. LOCKGLORIN Intrinsic Errors 



INCORRECT PASSWORD FOR RIN 

ONLY ONE RIN CAN BE LOCKED 

RIN IS NOT ALLOCATED 

RIN IS TOO LARGE FOR THE RIN TABLE 

RIN IS NOT GLOBAL RIN 
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Table E-ll. Private Volumes Error Messages 



PRIVATE VOLUMES FACILITY NOT INVOKED (PVERR 20) 

OPERATOR REJECTED MOUNT REQUEST (PVERR 21) 

INSUFFICIENT DRIVES AVAILABLE TO MOUNT VOLUME SET (PVERR 22) 

VOLUME SET TEMPORARILY IN USE BY SYSTEM (PVERR 23) 

GROUP IN VOLUME SET SPECIFICATION DOES NOT EXIST (PVERR 24) 

ACCOUNT IN VOLUME SET SPECIFICATION DOES NOT EXIST (PVERR 25) 

VOLUME SET IS NOT PHYSICALLY MOUNTED ON SYSTEM (PVERR 26) 

VOLUME SET/CLASS DEFINITION DOES NOT EXIST (PVERR 27) 

NO HOME VOLUME SET DESIGNATED FOR nnn (PVERR 28) 

GROUP IN HOME VOLUME SET SPECIFICATION DOES NOT EXIST (PVERR 29) 

ACCOUNT IN HOME VOLUME SET SPECIFICATION DOES NOT EXIST (PVERR 30) 

GROUP DOES NOT EXIST ON VOLUME SET (PVERR 31) 

ACCOUNT DOES NOT EXIST ON VOLUME SET (PVERR 32) 

VOLUME SET ALREADY MOUNTED BY THIS USER (PVERR 33) 

USER DOES NOT HAVE VOLUME SET MOUNTED (PVERR 34) 

OPERATOR DISMOUNT PENDING FOR VOLUME SET (PVERR 35) 

DOWN PENDING FOR DISC CONTAINING MEMBER VOLUME (PVERR 36) 

REQUEST FOR DIFFERENT MEMBERS THAN CURRENTLY IN USE (PVERR 37) 

MUST USE HOME VOLUME SPECIFICATION IN THIS CONTEXT (PVERR 38) 

CANNOT USE HOME VOLUME SET SPECIFICATION IN THIS CONTEXT (PVERR 39) 

VOLUME SET CURRENTLY MOUNTED WITH DIFFERENT GENERATION (PVERR 41) 

MOUNTED VOLUME TABLE ERROR (SYSTEM PROBLEM) (PVERR 50) 

VOLUME SET USER TABLE ERROR (SYSTEM PROBLEM) (PVERR 51) 

DIRECTORY ERROR (SYSTEM PROBLEM) (PVERR 52) 

LDEV# nnn IS OUT OF RANGE (PVERR 60) 

LDEV#nnn IS NOT CONFIGURED (PVERR 61) 

LDEV# nnn IS NOT A DISC (PVERR 62) 

LDEV# nnn IS NOT A REMOVABLE DISC (PVERR 63) 

LDEV# nnn IS NOT AN ALLOWED REMOVABLE DISC-INVALID SUBTYPE (PVERR 64) 

LDEV# nnn IS NOT IN THE USER DISC DOMAIN (PVERR 65) 

LDEV# nnn IS NOT ON-LINE (PVERR 66) 

LDEV# nnn IS A SERIAL DISC (PVERR 67) 

LDEV# nnn IS RESERVED FOR USE BY SYSTEM (PVERR 68) 

LDEV# nnn IS NOT DOWN-ED (PVERR 69) 

LDEV# nnn HAS DOWN PENDING (PVERR 70) 

LDEV# nnn IS IN USE BY PRIVATE VOLUMES (PVERR 71) 

** FUNCTION ABORTED ** 

UNRECOGNIZED FUNCTION (PVERR 101) 

INVALID TRACK DISPOSITION (PVERR 102) 

UNRECOGNIZED KEYWORD (PVERR 103) 

NO VOLUME SET CURRENTLY SPECIFIED (PVERR 104) 

LDEV# nnn NOT DOWNED (PVERR 105) 

LDEV# nnn NOT DOWNED OR SCRATCH (PVERR 106) 

VOLUME SPECIFIED IS NOT A MEMBER OF THE VOLUME SET (PVERR 107) 

SUBTYPE INCONSISTENCY BETWEEN DEVICES SPECIFIED (PVERR 108) 

PACK SIZE INCONSISTENCY BETWEEN DEVICES SPECIFIED (PVERR 109) 

ATTEMPTED TO COPY TO A BAD TRACK (PVERR 110) 

NO SUSPECT TRACKS FOUND 

NO ALTERNATE TRACKS AVAILABLE (PVERR 112) 

TRACK NOT REASSIGNED 

TRACK IN RESERVED AREA - MUST REFORMAT PACK (PVERR 114) 

INVALID NUMERIC VALUE FOR KEYWORD PARAMETER (PVERR 115) 

VOLUME NAME MORE THAN EIGHT CHARACTERS IN LENGTH (PVERR 1 16) 
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Table E-ll. Private Volumes Error Messages (Continued) 



VOLUME SET NAME MORE THAN EIGHT CHARACTERS IN LENGTH (PVERR 117) 

KEYWORD IS MORE THAN EIGHT CHARACTERS IN LENGTH (PVERR 1 18) 

VOLUME NAME HAS NON-ALPHA LEADING CHARACTER (PVERR 119) 

VOLUME SET NAME HAS NON-ALPHA LEADING CHARACTER (PVERR 120) 

KEYWORD HAS NON-ALPHA LEADING CHARACTER (PVERR 121) 

VOLUME NAME CONTAINS A SPECIAL CHARACTER (PVERR 122) 

VOLUME SET NAME CONTAINS A SPECIAL CHARACTER (PVERR 123) 

KEYWORD CONTAINS A SPECIAL CHARACTER (PVERR 124) 

NO PARAMETERS ALLOWED FOR THIS FUNCTION (PVERR 125) 

MISSING NON-OPTIONAL PARAMETER (PVERR 126) 

NON-NUMERIC CHARACTER IN LDEV SPECIFICATION (PVERR 127) 

INVALID LDEV VALUE (PVERR 128) 

TOO MANY NAMES IN VOLUME SET SPECIFICATION (PVERR 129) 

MISSING KEYWORD PARAMETER VALUE (PVERR 130) 

UNEXPECTED DELIMITER (PVERR 131) 

UNEXPECTED PARAMETER (PVERR 132) 

WARNING: VOLUME ALREADY nnn (PVWARN 140) 

WARNING: SUSPECT TRACK IN ALTERNATE AREA (PVWARN 141) 

WARNING: SUSPECT TRACK IN RESERVED AREA (PVWARN 142) 

WARNING: nnn SUSPECT TRACKS DETECTED (PVWARN 143) 



Table E-12. User Logging Error Messages 



MESSAGE NO. 




1 
2 
3 

4 

5 

6 

8 

9 

10 

12 

13 

14 

15 

16 



MESSAGE 



No error occurred for this call. 

User requested no wait mode and the logging process is busy. 

Parameter out of bounds in logging intrinsic 

Request to open or write to a logging process that isn't 

running. 

Incorrect index parameter passed a logging intrinsic 

Incorrect mode parameter passed to logging intrinsic 

User request denied because logging process is suspended. 

incorrect password passed to logging intrinsic. 

Error occurred while writing logging file. 

Invalid DST passed to logging system intrinsic. 

System is out of disc space logging cannot proceed. 

No more logging entries. 

Invalid access to logging file. 

End of file on user log file. 

Invalid logging identifier. ^^ 
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Table E-13. CLEANUSL Error Messages 



ERROR NUMBER MESSAGE 



The file specified by uslfnum was empty, or unexpected end-of-file 
was encountered when reading the old uslfnum, or an unexpected 
end-of-file was encountered when writing on the new uslfnum. 

1 Unexpected input/output error occurred. This can occur on the 
old uslfnum or the new uslfnum to which the intrinsic is copying 
the information. 

3 Your request attempted to exceed the maximum file directory size 

(32,768 words). 

6 Insufficient space was available in the USL file information block. 

7 The intrinsic was unable to open the new USL file. 

8 The intrinsic was unable to close (purge) the old USL file. 

9 The intrinsic was unable to close (purge) the new USL file. 

I ° The intrinsic was unable to close $N EWPASS. 

I I The intrinsic was unable to open $OLDPASS. 
12 Illegal USL file format. 
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Table E-14. CREATEPROCESS Error Messages 



ERROR NUMBER 



MESSAGE 



1 

2 

3 

4 

5 

6 

7 



Process created as requested. 

Caller lacks PH capability. 

Required parameter (other than error) omitted. 

Parameter address (other than error) out of bounds. 

Out of system resources (PCB's, DST's, etc.) 

Process not created because an invalid item number was specified. 

Process not created because progname does not exist. 

Process not created because progname is invalid. 



8 
- 9 

-10 

-11 

-12 
-13 
-14 

15 



17 

18 
19 
20 



Process not created because entryname does not exist or is invalid. 

Process created with default stacksize from progfile (specified 
stacksize was <512). 

Process created with default dlsize from progfile (specified dlsize 
was <0). 

Process created with default maxdata from progfile (specified 
maxdata was <= 0). 

Process created with dlsize rounded up to next 128 word multiple. 

Process created with maxdata decreased to configuration maximum. 

Process created with maxdata increased to dlsize+globsize+stacksize 
(globsize is defined to be primary DB space+secondary DB space). 

Process not created because dlsize+globsize+stacksize was > con- 
figuration maximum stacksize. 

i-. ^ a I I . « "Urt.-^J" In^rl nrrrw r^ffl irrorl tpn I/O 

rrocess nui ureaieu un*auac a uqiu luau onvi wwv,«.i«« *-. 3 . ■■ ~ 

error reading progfile, etc.). 

Process not created because an illegal value was specif ied for priority- 
class. 

Process not created because specified $STDIN could not be opened. 
Process not created because specified $STDLIST could not be opened. 

Process not created because string to be passed to new process was 
invalid (pointer without length, length without pointer, or length 
exceeds stack size of calling process). 
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USER MESSAGES 

When your batch job or session receives a message from another user's job or session, that message 
appears in the following format: 



FROM/ 1 I num, username.acctname/message 



jsname 

username 

acctname 



The names of the transmitting job/session and user, and the name of 
the account under which they are running. 



message The message. 

As an example, if a user identified as BOB running a session under an account named MPE, sends a 
message to you that he is changing the name of a file used frequently by both programs: you would 
see the following message: 

FROM/S106 BOB.MPE/DO NOT USE FILE TR7 



OPERATOR MESSAGES 

When your batch job or session receives a message from the console operator, that message appears 
in one of two formats, depending on its degree of urgency. Urgent messages which pre-empt any 
form of input/output being conducted on the standard list device, appear in this format: 

OPERATOR WARNING/message 

message is the message text. 

Less serious messages used for normal communication between the operator and you do not pre- 
empt input/output in progress, and appear on the standard list device in this format: 
FROM OPERA TOR : message 

message is the message text. 

SYSTEM MESSAGES 

Miscellaneous conditions that terminate or otherwise affect your job/session are reported through 
system messages, shown in table E-ll. These messages may appear, asynchronously, during the 
course of a running job/session on the standard list device. 
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Table E- 15. System Messages 



CAN'T INITIATE NEW SESSIONS NOW 

New sessions cannot be initiated due to one of the following problems: 

1. Insufficient system resources to start job. 

2. Session limit would be exceeded (see = LIMIT and = LOGOFF). 

3. Requestor's input priority (INPRI =) is not greater than current <jobfence >(see = JOBFENCE). 

NOTE: System managers and system supervisors can bypass rejections due to 2 and 3, above, by 
supplying HI PR! on : HELLO command. 



| SESSION \ ABORTED BY SYSTEM MANAGEMENT, 

| JOB J 



The job/session has been aborted by the computer operator or system supervisor user through the appropriate 
command. An immediate log-off then takes place. 



| SESSION \ HAS EXCEEDED TIME LIMIT, 

\ JOB ) 



The job/session has exceeded the time limit which was specified in the TIME=parameter of the JOB/HELLO 
command. An immediate log-off then takes place. 

WARNING: PRIORITY = XXX 

The priority passed to the CREATE intrinsic resulted in a conflict with another process, and the priority then 
assigned was XXX instead of the requested value. 

LMAP NOT AVAILABLE 

An LMAK ot tne process Deing creaiea, or program me uemy .nun, i=> nm ava,<au,^ ^o^^..^ ... .~ — „ 

are already loaded. 

**POWER FAIL** 

Power failure has occurred and automatic restart is in progress. It is possible that a character has been lost due 
to a transmission error when the power failure occurred. 
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FILE INFORMATION DISPLAY 

In addition to Command Interpreter and run-time (abort) error messages, certain file input/output 
errors result in the output of a file information display. For files not yet opened, or for which 
the FOPEN intrinsic failed, this display appears as in the example below. 



+-F-I-L-E I-N-F-0-R-M-A-T-I-O-N D- I-S-P-L-A-Y+ 

U>-^! FILE NUMBER 5 IS UNDEFINED. • 

@ — -! ERROR NUMBER: 2 RESIDUE: (WORDS) ! 
Qy-* % - BLOCK NUMBER: NUMREC: ! 

-+ + 

In this display, the lines indicated show the following information. 
Line Content 

1 A warning that there is no corresponding file open. 

2 The appropriate error number, relating to table E-4. The residue, which 

is the number of words not transferred in an input/output request; 
since no such request applies in this case, this is zero. 



NOTE 
This will always be the last FOPEN error for the calling program. 

The block number, and numrec fields will always be zero in this short 
form. 



For files that were open when a CCG (end-of-file error) or CCL (irrecoverable file error) condition 
code was returned, the file information display appears as shown in this example: 




© 
0- 
© 
© 

0. 

© 



♦ -F-I-L-E---I-M-F-0-P-!«-A-T-l-o-N---r--]>S-P' 
— -! FILE NAME IS I N . VOLLMEP ,CMF TO,! 

— -I F'nPTIOMS: Mf w. A, *FUPML#,F,w,F£Q,T 

— -! ACIPTI0N5: I ^ PUT, SFEC,Nni,OCK,DEF, BUFFER 

»-! DEVICE TYPE: DEVICE SUBTYPE; 9 

0— ^i LDEV: 2 D«T; 4 UNIT; j 



0- 



0- 



©- 



«3 



-I-S-P-L-A-Y+ 



DEVICE TYPE: 
LDEV: 2 D^T 
RECORD SIZE: 256 
EXTENT SIZE: 12H 
PECPTR: 
LOGCOIWT: 
EOF AT; 
FILE CODE: 
PHYSICAL- STATUS: 
ERROR MIJMREP: 
BLOCK Mt'MBEP: 



4 UM'TT; 

BLOCK SIZE: 25b 
MX f-XTE^TS: A 
PECLIMTT: 102 3 

PHYSCUUNT; 
LABEL ADDP: %' 
ID TS JOE 

1 ooonoooooonooni 
RESIDUE: 

NUMREC 



(BYTES) 



00201 377*30 
ULABFLS; 



1 
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The lines indicated show the following information: 
Line 



1 
2 



Content 

The file name: in this case, the name is IN.VOLLMER.CLIFTON 

The foptions in effect, including: 

Domain: NEW = New file (as in this case). 

SYS = System file domain. 

JOB = Job temporary file domain. 

ALL = System and job temporary file domain. 



Type: 



Default File 
Designator: 



Record 
Format: 



A = ASCII File (as in this case). 
B = Binary File. 

*FORMAL* = Actual file designator is same as 
formal file designator. 

$STDIN 

$STDLIST 

$STDINX 

$NEWPASS 

$OLDPASS 

$NULL 

Fixed length, (as in this case) 

V = Variable length. 

U = Undefined length (as in this case). 

? = Unknown format. 



Carriage N = None (as in this case). 

Control: C = Carriage control character expected. 

File Equation FEQ = :FILE allowed (as in this case). 

Ontinn: DEO = :FILE not allowed. 

Labeled T = Not a labeled tape (as in this case) 

Tape Option: L = Labeled tape 



mi a- 1~ ~££ J. ^ l..*J4~t,*. 

ine aoplWJris in eueti/, uiuuumg. 



Access Type: INPUT 

OUTPUT 

OUTKEEP 

APPEND 

IN/OUT 

UPDATE 



= Read access (as in this case). 

= Write access. 

= Write-only access, without deleting. 

= Append access. 

= Input and output access. 

= Update access. 



Multi-record SRiiC = Single record access (as in this case). 
Option: MREC = Multi-record access. 
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Line Contents 

3 Dynamic NOLOCK = No locking permitted (as in this case). 

(Cont.) Locking LOCK = Locking permitted. 

Option : 

Exclusive DEF = Default specification (as in this case). 

Access EXC = Exclusive access allowed. 

Option: SEA = Semi-exclusive access allowed. 

SHR = Sharable file. 
Buffering: BUFFER = Automatic buffering (as in this case). 

NOBUFF = Inhibit buffering 

4 > 5 The Device Type, Device Subtype, LDEV (Logical Device Number), 

DRT (Device Reference Table Entry Number) and Unit of the device 
on which the file resides. (These are 0, 9, 2, 4, and 1 respectively, in 
this case.) If the file is a spoolfile, the LDEV will be a "virtual" rather 
than a physical device number. See Idnum under FGETINFO. 

6 The record size and block size of the offending record, in bytes or 

words as noted. (In this case, these are both specified as 256 bytes.) 

7 The extent size (of the current extent) and the max extents (maximum 

number of extents) allowed this file. 

8 The recptr (current record pointer) and reclimit (limit on number of 

records in the file). 

9 The logcount (present count of logical records) and physcount (present 

count of- physical records) in the file. 

10 The EOF at (location of the current end-of-file) and the label addr 

(location of the header label of the file). 

11 The file code, id (name of creating user), and ulabels (number of 

user-created labels) for the file. 

12 The physical status of the file. 

13 The error number and residue, as described under the abbreviated file 

information display format, above. 

14 The block number and numrec, as described under the abbreviated file 

information display format, above. 
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Aborting a process, 4-20 
Aborting a program, 4-20 
Accessing files, 10-8 
Accessing files already in use, 10-12 
Access-mode options for files, 10-91 
Access mode, user, 4-10 
Acquiring global RIN's, 6-2 
Acquiring local RIN's, 6-8 
ACCEPT intrinsics, 2-4 
ACTIVATE errors, E-l 3 
ACTIVATE intrinsic 

specifications, 2-5 

usage, 8-10 
Activating an extra data segment, 8-10 
Activating processes, 7-3 
Actual file designator, 10-10 
ADJUSTUSLF intrinisc, 2-7 
Allocation of devices, 10-25, 10-26 
Allocating a terminal, 5-24 
ALTDSEG intrinsic 

specifications, 2-9 

usage, 8-15 
Aoptions 

bit summary, 2-51 

description, 2-61 
Arithmetic traps, 4-30 
ARITRAP intrinsic 

specifications, 2-11 

usage, 4-30 
Arrays, searching, 4-3 
ASCII intrinsic 

specifications, 2-12 

usage, 4-10 
AS subqueue, 9-7 
Attributes, user, 4-10 
Available file table (AFT), 10-17 
Avoiding deadlocks, 7-13 

B 

Back referencing files, 10-10 
BEGINLOG intrinsics, 2-13a 
BINARY intrinsic 
specifications, 2-14 
usage, 4-13 

Block factor, 2-65, 10-3 

Blocks, 10-2 

Block size, 10-4 

Block transfers, 5-22 

Bounds check, 1-11 

BS subqueue, 9-7 

Biiffnnnx 1 f»_7 



Calculating disc space, 10-2 
Calendar date, 444 
CALENDAR intrinsic 
specifications, 2-15 
usage, 4-44 
Calling intrinsics from other languages, 1-10 
Calling intrinsics from SPL, 1-2 
Card reader, 5-3 
Carriage control 
byte, 2-70 
characters, 5-1 
codes, 5-7 
directives, 2-89, 5-7 
summary, 2-90 
Carriage-return characters, 5-2 
CAUSEBREAK intrinsic 
specifications, 2-16 
usage, 4-19 
Central processor run-timer, 4-44 
Changing DL to DB area size, 4-22 
Changing input echo facility, 5-11 
Changing size of an extra data segment, 8-15 
Changing terminal characteristics, 5-10 
Changing terminal speed, 5-10 
Changing Z to DB area size, 4-27 
Circular Files, 3-9 through 3-12 

Features of intrinsics, 3-10 
Circular subqueues, 9-5 
Classification of devices, 10-25 
CLEANUSL intrinsic 

specifications, 2-17 
CLOCK intrinsic 
specifications, 2-18 
usage, 4-44 
CLOSELOG intrinsic 
specifications, 2-19 
usage, 10-93 
Closing a new file as a permanent file, 10-40 
Closing a new file as a temporary file, 10-39 
Closing files, 10-39 
Closing magnetic tape files, 10-73 
COBOL II 



r JJCiJUEiTEi, Z-Dl 

FFILEINFO,2-63 

Relative I/O, 10-6 
Code segments, 8-1 
Collecting mail, 7-12 
COMMAND intrinsic 

specifications, 2-20 

usage, 4-9 
Command parameters, formatting, 4-4 
Commercial instruction traps, 4-31 
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Communication 

inter-process, 4-44, 7-10 

process-to-process, 7-2 
Condition codes 

definitions, 1-11 
| file system, 10-12 

Console Operator, 4-18 
Control-Y traps, 4-38 
Converting characters from EBCDIC to ASCII and 

ASCII to EBCDIC, 4-13 
Converting numbers 

from ASCII to binary, 4-13 

from ASCII to EBCDIC, 4-13 

from binary to ASCII, 4-10 

from EBCDIC to ASCII, 4-13 
Copy access, for message files, 3-3,3-8 
CREATE errors, E-13 
CREATE intrinsic 

specifications, 2-21 

usage, 7-3 
CREATEPROCESS intrinsic, 2-26 

errors, E-17 
Creating an extra data segment, 8-2 
Creating processes, 7-3 
CS subqueue, 9-7 
CTRANSLATE intrinsic 

specifications, 2-28 

usage, 4-13 
Current time, 4-44 



Determining source of process activation, 7-14 
Determining user's access mode attributes, 4-10 
Device access, 10-7 
Device allocation, 10-26 
Device characteristics, 5-1 
Device control (2680A Printer), 2-61a 
Device -dependent restrictions on files, 10-24 
Devices, 10-7 

Devices, classification of, 10-25 
Direct-access file reading, 10-49 
Direct-access file writing, 10-51 
Disabling traps, 4-29 
Disc space, 10-2 
DLSIZE intrinsic 
specifications, 2-35 
usage, 4-22 
DL to DB area, 4-22 
DMOVIN intrinsic 
specifications, 2-37 
usage, 8-15 
DMOVOUT intrinsic 
specifications, 2-39 
usage, 8-15 
Domains, file, 10-7 
DS subqueue, 9-7 
Duplex mode, 5-11 
Duplicate file pairs, 10-92 
Dynamic loading and unloading of library procedures, 4-2 
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DASCII intrinsic 

specifications, 2-30 

usage, 4-13 
Data segments, 8-1 

changing the size, 8-15 

deleting, 8-15 

transferring to and from, 8-15 
Data information, 4-42 
DATELINE intrinsic, 2-32 
DBINARY intrinsic 

specifications, 2-33 

usage, 4-13 
DB pointer, 9-5 
Deadlocks, 7-13 
DEBUG intrinsic, 2-34 

Declaring access-mode options for files, 10-91 
Defining line-termination characters for 
terminal input, 5-20 
Deleting an extra data segment, 8-15 
Deleting processes, 7-8 
DENsity selection on labeled and 

and unlabeled tapes, 10-89 
DENsity Specification, FOPEN, 2 -88a 
Determining father process, 7-14 
Determining interactive and duplicative file pairs, 10-92 
Determining process priority and state, 7-15 
Determining son processes, 7-15 



Effective Use of User Logging, 10-96 
Enabling and disabling binary transfers, 5-21 
Enabling and disabling line deletion 

echo suppression, 5-23 
Enabling and disabling parity checking, 5-14 
Enabling and disabling subsystem break function, 5-14 
Enabling and disabling system break function, 5-13 
Enabling and disabling tape-mode option, 5-15 
Enabling and disabling terminal input timer, 5-16 
Enabling and disabling user block transfers, 5-22 
Enabling traps, 4-29 
End-of-file indication, 5-6 
End-of-file marks on magnetic tape, 10-72 
ENDLOG intrinsic, 2 -40a 
ENVironment File 

Specification, FOPEN, 2 -88a 
Entering non-privileged mode, 9-5 
Entering privileged mode, 9-3 
Error-check procedure, 10-45 
Errors 

ACTIVATE errors, E-13 

condition code, 1-10, 10-12 

CREATE errors, E-13 

CREATEPROCESS errors, E-17 

file information display, E-20 

file system errors, E-8 

intrinsic errors, E-6 

loader errors, E-12 
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LOCKGLORIN errors, E-13 

MYCOMMAND errors, E-13 

obtaining file error information, 10-68 

operator messages, E-18 

program errors, E-5 

run-time errors, E-7 

run-time messages, E-2 

SUSPEND errors, E-13 

system messages, E-18 

user messages, E-18 

writing an error-check procedure, 10-45 
ES subqueue, 9-7 

Executing MPE commands programmatically, 4-9 
EXPANDUSLF intrinsic, 2-41 
Extended precision floating-point traps, 4-31 

Extents, 10-2 

Extra data segment, 8-2 



FATHER intrinsic 

specifications, 2-43 

usage, 7-14 
Father process, 7-3 
FCARD intrinsic 

specifications, 2-44 

usage, 5-28 
FCHECK intrinsic 

specifications, 2-48 

usage, 10-69 
FCLOSE intrinsic 

specifications, 2-54 

usage, 10-38 
FCLOSE with magnetic tape files, 10-73 
FCONTROL intrinsic 

specifications, 2-57 

usage, 5-1, 10-79 
FDELETE intrinsic, 2-61 

specifications, 2-61 

usage, 10-9 
FDEVICEVONTROL intrinsic, 2 -61a 
FERRMSG intrinsic, 2-62 

usage, 10-69 
FFILEINFO intrinsic 

usage, 10-68 
FGETINFO intrinsic 

specifications, 2-65 

usage, 10-66 
File accessing, 10-12, 10-17 
File characteristics, 10-2 
File control operations, 10-90 
File designators, 10-10 
File-device relationships, 10-7 
File domains, 10-7 
File error information, 10-68 
File information display, E-20 
File label, 10-8 
File management system 10-1 



File marks on magnetic tape, 10-72 

File numbers, 10-12 

Files 

access information, 10-66 

accessing, 10-8 

back referencing 10-10 

block factor, 10-3 

blocks, 10-2 

block size, 10-4 

buffered, 2-63 

characteristics, 10-2 

closing, 10-39 

condition codes, 10-12 

control, 10-90 

declaring access-mode options, 10-91 

designators, 10-8 

device relationships, 10-7 

disc, 10-2 

domains, 10-7 

duplicative pairs, 10-92 

error-check procedure, 10-45 

error information, 10-68 

extents, 10-2 

file information display, 10-14 

file management system, 10-1 

fixed-length records, 10-3 

foreign disc facility, 10-32, 10-47, 10-49, 10-50, 10-51 

how to use, 10-17 

interactive pairs, 10-92 

label, 10-8 

locking and unlocking, 10-55 

logical records, 10-2 

magnetic tape, 10-69 

multiple access, 10-12, 10-13 

$NEWPASS, 10-10 

non-sharables devices, 10-15 

no-wait I/O, 10-59, 10-60 

$NULL, 10-10 

numbers, 10-12 

$OLDPASS, 10-11 






permanent, 10-14, 10-40 

physical records, 10-2 

pointer, 10-91 

reading, 10-47, 10-49 

record formats, 10-3 

records, 10-2 

relative I/O, 10-6, 10-8 

renaming, 10-43 

sectors, 10-2 

shared, special considerations, 10-16 

spooling, 10-23 

$STDIN, 10-9 

$STDINX, 10-10 

d*omT»T TcrTi in m 

system defined, 10-9 
temporary, 10-7 
types, 10-8 
undefined-length records, 10-3 
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unlocking, 10-55 

updating, 10-57 

user labels, 10-62 

user logging, 10-93 

using, 10-17 

variable-length records, 10-3 

writing, 10-49, 10-50 
Piles on non-sharable devices, 10-50 
File system condition codes, 10-12 
File system errors, E-8 
File types, 10-8 
FINDJCW intrinsic 

specifications, 2-74 

usage, 4-47 
Fixed-length records, 10-3 
FLOCK intrinsic 

specifications, 2-75 

usage, 10-55 
FLUSHLOG intrinsic, 2-76a 
FMTCALENDAR intrinsic 

specifications, 2-77 

usage, 4-45 
FMTCLOCK intrinsic 

specifications, 2-78 

usage, 4-45 
FMTDATE intrinsic 

specifications, 2-79 

usage, 4-45 
FOPEN intrinsic 

specifications, 2-80 

usage, 10-26 
Foptions 

bit summary, 2-49 

description, 2-58 
Foreign Disc Facility, 10-32, 10-37, 10-49, 10-50, 10-51 
Formal file designator, 10-8 
Formatting Calendar date and time, 4-45 
Formatting command parameters, 4-4 
FPOINT intrinsic 

specifications, 2-94 

usage, 10-9 
FREAD and FWRETE for $STDIN and $STDLIST, 10-35 
FREAD for magnetic tape files, 10-71 
FREAD intrinsic 

specifications, 2-95 

usage, 1047 
FREADBACKWARD intrinsic, 2-97 
FREADDIR intrinsic 

specifications, 2-99 

usage, 10-49 
FREADLABEL intrinsic 

specifications, 2-101 

usage, 10-63 
FREADSEEK intrinsic 

specifications, 2-102 

usage, 10-52 
FREEDSEG intrinsic 

specifications, 2-103 

"sage, 8-15 



Freeing local RIN's 6-9 
FREELOCRIN intrinsic 

specifications, 2-104 

usage, 6-9 
FRELATE intrinsic 

specifications, 2-105 

usage, 10-92 
FRENAME intrinsic 

specifications, 2-107 

usage, 10-43 
FSETMODE intrinsic 

specifications, 2-109 

usage, 10-91 
FSPACE intrinsic 

specifications, 2-111 

usage, 10-89 
Functional return, 2-2 
FUNLOCK intrinsic 

specifications, 2-113 

usage, 10-56 
FUPDATE intrinsic 

specifications, 2-114 

usage, 10-58 
FWRITE and FREAD for $STDLIST and $STDIN, 10-35 
FWRITE for magnetic tape files, 10-71 
FWRITE intrinsic 

specifications, 2-115 

usage, 10-48 
FWRITEDIR intrinsic 

specifications, 2-120 

usage, 10-53 
FWRITELABEL intrinsic 

specifications, 2-122 

usage, 10-64 



GENMESSAGE intrinsic 

specifications, 2-123 

usage, 4-50 
GET intrinsic, 2-126 
GETDSEG intrinsic 

specifications, 2-127 

usage, 8-6 
GETJCW intrinsic 

specifications, 2-129 

usage, 4-46 
GETLOCRIN intrinsic 

specifications, 2-130 

usage, 6-8 
GETORIGIN intrinsic 

specifications, 2-131 

usage, 7-14 
GETPRIORITY intrinsic 

specifications, 2-132 

usage, 7-13 
GETPRIVMODE intrinsic 

specifications, 2-134 

usage, 9-3 
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GETPROCID intrinsic 

specifications, 2-135 

usage, 7-15 
GETPROCINFO intrinsic 

specifications, 2-136 

usage, 7-15 
:GETRIN command, 6-2 
GETUSERMODE intrinsic 

specifications, 2-138 

usage, 9-5 
Global multiaccess, for circular files, 3-10 

for message files, 3-3, 3-6 
Global RIN's, 6-2 

H 

HP 2680A Printer, 2-61a, 2-88a 

Hand-shaking arrangement, 6-1 

How to use files, 10-17 

How user logging works, 10-94 

Hand-shaking arrangement, 6-1 

How to use files, 10-17 

How user logging works, 10-94 
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Identifying Local RIN owners, 6-9 

INITUSLF intrinsic, 2-137 

Input echo facility, 5-11 

Input/output devices, 4-16 

Input/output files, 10-11 

Interactive file pairs, 10-92 

Inter-job level RIN's, 6-2 

Internal operations for file accessing, 10-17 

Interprocess Communication (IPC), 3-1 through 3-21 

additional features, 3-2 

examples, 3-12 

features of intrinsics, 3-5 

operation, 3-1 

using, 3-3 
Inter-process level RIN's, 6-6 
Inter-record gap, 10-76 
Intrinsic errors, 10-6 
Intrinsics 

ACTIVATE, 2-5, 8-10 
ADJUSTUSLF, 2-7 
ALTDSEG, 2-9, 8-16 
ARITRAP, 2-11,4-30 
ASCII, 2-12, 4-10 
BEGINLOG, 2-13a 
BINARY, 2-14,4-13 
CALENDAR, 2-15, 4-44 
calling from other languages, 1-10 
calling from SPL, 1-2 
CAUSEBREAK, 2-16,4-19 
CLEANUSL, 2-17 
CLOCK, 2-18,4-44 
CLOSELOG, 2-19 



COMMAND, 2-20,4-9 
CREATE, 2-21, 7-3 
CREATEPROCESS, 2-26 
CTRANSLATE, 2-28, 4-13 
D ASCII, 2-30,4-13 
DATELINE, 2-32 
DBINARY, 2-33,4-13 
DEBUG, 2-34 
declaration, 1-2 
definition, 1-1 
DLSIZE, 2-35, 4-22 
DMO VIN, 2-37, 8-15 
DMO VOUT, 2-39,8-15 
error definitions, 1-10 
error messages, E-l 
ENDLOG, 2 -40a 
EXPANDUSLF, 2-41 
FATHER, 2-43,7-14 
FCARD, 2-43, 5-28 
FCHECK, 2-44, 2-48, 10-70 

FCLOSE, 2-54, 10-73 
FCONTROL, 2-57, 5-1, 10-79 
FDELETE, 2-61, 10-9 
FDEVICECONTROL, 2 -61a 
FERRMSG, 2-62,10-69 
FFILEINFO, 2-63, 10-68 
FGETINFO, 2-65, 10-66 
FINDJCW, 2-74, 4-47 
FLOCK, 2-75, 10-55 
FLUSHLOG,2-76a 
FMTCALENDAR, 2-77, 4-45 
FMTCLOCK, 2-78, 445 
FMTDATE, 2-79, 445 
FOPEN, 2-80,10-25 

for Interprocess Communication, 3-5 

for Circular Files, 3-10 
FPOINT, 2-94, 10-9 
FREAD, 2-95, 1047 
FREADBACKWARD, 2-97 
FREADDIR, 2-99, 1049 

T7T1T? ATM AT>T?T 0.101 1fl_£Q 
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FREADSEEK, 2-103, 10-52 
FREEDSEG, 2-103, 8-15 
FREELOCRIN, 2-104, 6-9 
FRELATE, 2-105, 10-92 
FRENAME, 2-107, 1043 
FSETMODE, 2-109, 10-91 
FSP ACE, 2-111,10-89 
FUNLOCK, 2-113, 10-56 
FUPDATE, 2-114, 10-58 
FWRITE, 2-115, 1048 
FWRITEDIR, 2-120, 10-53 
FWRITELABEL, 2-122, 10-64 
GENMESSAGE, 2-123, 4-50 
GET, 2-126 
GETDSEG, 2-127, 8-6 
GETJCW, 2429,446 
GETLOCRIN, 2-130, 6-8 
GETORIGIN, 2-131, 7-14 
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GETPRIORITY, 2-132, 7-13 
GETPRIVMODE, 2-134, 9-3 
GETPROCID, 2-135, 7-15 
GETPROCINFO, 2-136, 7-15 
GETUSERMODE, 2-138, 9-5 
EMITUSLF, 2-125 
IODONTWAIT, 2-140, 10-62 
IOWAIT, 2-142, 10-59 
KILL, 2-144, 7-8 
LOADPROC, 2-145, 4-2 
LOCKGLORIN, 2-146, 6-3 
LOCKLOCRIN, 2-148, 6-8 
LOCRINOWNER, 2-150, 6-9 
LOGSTATUS, 2 -150a 
MAIL, 2-151,7-10 
MYCOMMAND, 2-153, 4-4 
OPENLOG, 2-156, 3-94 
PAUSE, 2-157, 4-19 
PCHECK, 2-158 
PCLOSE, 2-159 
PCONTROL, 2-160 
POPEN, 2-161 
PREAD, 2-162 

PRINT, 2-163, 4-16 
PRINTFILEINFO, 2-164, 10-45, 10-47 
PRINTOP, 2-165,4-18 
PRINTOPREPLY, 2-166, 4-18 
PROCTIME, 2-168, 4-44 
PTAPE, 2-169, 5-27 
purposes, 1-1 
PUTJCW, 2-170,4-47 
PWRITE, 2-171 
QUIT, 2-172, 4-20 
QUITPROG, 2-173, 4-22 
READ, 2-174,4-16 
READX, 2-175,4-16 
RECEIVEMAIL, 2-176, 7-12 
REJECT, 2-178 

RESETCONTROL, 2-179, 4-40 
RESETDUMP, 2-180 
SEARCH, 2-181,4-3 
SENDMAIL, 2-182, 7-11 
SETDUMP, 2-183 
SETJCW, 2-185, 4-46 
STACKDUMP, 2-186 
summary, 1-3 
SUSPEND, 2-188, 7-8 
SWITCHDB, 2-189, 9-5 
TERMINATE, 2-190,4-20 
TIMER, 2-191, 4-42 
types, 2-2 

UNLOADPROC, 2-192,4-3 
UNLOCKGLORIN, 2-193, 6-3 
UNLOCKLOCRIN, 2-194, 6-8 
WHO, 2-195, 4-10 
WRITELOG, 2-198, 10-94 
XARITRAP, 2-199, 4-32 
XCONTRAP, 2-201, 4-41 
XLIBTRAP, 2-202, 4-35 



XSYSTRAP, 2-203, 4-36 

ZSIZE, 2-204,4-27 
IODONTWAIT intrinsic 

specification, 2-140 

usage, 10-62 
IOWAIT intrinsic 

specifications, 2-142 

usage, 10-59 
IPC — see Interprocess Communication 
Issuing FREAD and FWRITE calls for 
$STDIN and $STDLIST, 10-35 



Job control words, 4-47 

Job main process, 7-1 

Job or session file domains, 10-7 

Job/session input/output devices, 4-16 

Job temporary file directory, 10-20 

Julian calendar, 8-8 

K 

Keys, terminals, 5-9 
KILL intrinsic 

specifications, 2-144 

usage, 7-8 



Labeled magnetic tape file 

density selection, 10-89 

opening, 10-81 

reading, 10-87 

writing, 10-84 
Library procedures, 4-2 
Library traps, 4-34 
Linear subqueue, 9-5 
Line deletion echo suppression, 5-23 
Line printer, 5-3 

Line printer and terminal carriage-control codes, 5-6 
Line-termination characters for terminal input, 5-20 
Loader errors, E-12 
Loading library procedures, 4-2 
LOADPROC intrinsic 

specifications, 2-145 

usage, 4-2 
Local RIN's, 6-6 

Locking and unlocking files, 10-56 
Locking and unlocking global RIN's, 6-3 
Locking and unlocking local RIN's, 6-8 
LOCKGLORIN errors, E-13 
LOCKGLORIN intrinsic 
specifications, 2-146 
usage, 6-3 
LOCKLOCRIN intrinsic 
specifications, 2-148 
usage, 6-8 
LOCRINOWNER intrinsic 
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specifications, 2-151 

usage, 6-9 
Logging, user, 10-93 

BEGINLOG, 2-13a 

ENDLOG 2-40a 

FLUSHLOG, 2-76a 

LOGSTATUS, 2-150a 

OPENLOG, 2-156 

CLOSELOG, 2-19 

WRITELOG, 2-198 
Logical index number, 8-2 
Logical record pointer, 10-91 
Logical records, 10-2 
LOGSTATUS intrinsic, 2-150a 

M 

Magnetic tape considerations for files, 10-69 
Magnetic tape labels, D-l 
Magnetic tape unit, 5-3 
Mailbox, 7-10 
MAIL intrinstic 

specifications, 2-151 

usage, 7-10 
MAKECAT program, 4-50 
Master queue, 9-5 
Message Files, 3-1 through 3-21 
Message system 4-48 

message catalog, 4-48 

MAKECAT program, 4-49 
Messages 

operator, 10-18 

run-time, E-2 

system, 10-18 

user, 10-18 
Moving the DB pointer, 9-5 
Multi-access, 10-12 
Multiple access of files, 10-13 
Multiple RENT optional capability, 6-1 
MYCOMMAND errors, E-l 3 
MYCOMMAND intrinsic 

specifications, 2-153 

usage, 4-4 



M 



New files, 10-10 

$NEWPASS, 10-10 

Nondestructive read, for message files, 3-3, 3-8 

Non-sharable device access, 10-7 

Non-sharavle devices, 10-15 

No-wait I/O, 10-62 

$NULL, 10-10 



O 



Obtaining file access information, 10-66 
Obtaining file error information, 10-68 
Obtaining process run time, 4-44 



Obtaining system timer information, 4-42 

Obtaining terminal output speed, 5-26 

Obtaining terminal type information, 5-25 

Obtaining the calendar data, 4-44 

Obtaining the current time, 4-44 

Old files, 10-11 

$OLDPASS, 10-11 

Opening a file on a device other than disc, 10-34 

Opening a new disc file, 10-38 

Opening an old disc file, 10-31 

Opening files, 10-27 

Opening $STDIN, 10-36 

Opening $STDLIST, 10-36 

OPENLOG intrinsic 

specifications, 2-156 

usage, 10-94 
Operator messages, E-18 
Operator's Console, 4 - 18 
Operator intervention, 

tape labels, 10 -75a 
Optical Mark Reader, 5-28 
Optional capabilities 

data segment management, 8-1 

definitions, 1-12 

multiple resource, 6-1 

privileged mode, 7-1 

process handling, 7-1 
Optional parameters, 1-7 
Option variable, 1-7, 2-1 
Organization of user processes, 7-1 



Paper tape punch, 5-3 
Paper tape reader, 5-1 
Paper tapes, 5-21 
Parameters 

definition, 1-7 

optional, 1-7 

option variable, 1-7 

: l... l.,_ 1 1 

passing uy voiuc, j.- i 

positional, 1-7 

required, 1-8 

using numeric values, 1-8 
Parity checking, 5-14 
Parity, setting, 5-23 
Passing parameters, 1-7 
PAUSE intrinsic 

specifications, 2-157 

usage, 4-19 
Permanent files, 10-14, 10-40 
Permanently privileged programs, 9-1 
PCHECK intrinsic, 2-158 
PCLOSE intrinsic, 2-159 
PCONTROL intrinsic, 2-160 
Physical records, 10-2 
PIN, 7-1 

POPEN intrinsic, 2-161 
Positional parameters, 1-7 
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PRE AD intrinsic, 2-162 
Pre-defined files, 10-10 
PRINT intrinsic 

specifications, 2-163 
usage, 4-16 
PRINTFILEINFO intrinsic 
specifications, 2-166 
usage, 10-45, 10-47 
Printing reader/punch, 5-3 
PRINTOP intrinsic 
specifications, 2-165 
usage, 4-18 
PRINTOPREPLY intrinsic 
specifications, 2-166 
usage, 4-18 
Private data area, 7-1 
Private volumes errors, E-14 
Private volumes subsystem, 10-17 
Privileged programs, 9-1 
Privileged mode capability, 9-1 
Procedures, 1-1 
Procedure type, 2-2 
Process activation, 7-14 
Process break, 4-19 
Process control block extension, 10-17 
Processes 

aborting, 4-20 
activating, 7-3 
avoiding deadlocks, 7-13 
breaking, 4-19 
creating, 7-3 
deleting, 7-8 
description, 7-1 
father, 7-3 

identification number, 7-1 
inter-process communication, 4-44 
mail, 7-10 
organization, 7-2 
priority, 7-15 

process-handling capability, 7-1 
rescheduling, 7-13 
run time, 4-44 
scheduling, 9-5 
son, 7-3 
state, 7-15 
substate, 7-2 
suspending, 4-19, 7-8 
terminating, 4-20 
Process-handling capability, 7-1 
Process identification number, 7-1 
Process priorities, 7-15 
Process run time, 4-44 
Process states, 7-15 
Process substates, 7-2 
Process -to -process communication, 7-2 
PROCINFO intrinsic 

specifications, 2-167a 
PROCTIME intrinsic 
specifications, 2-168 
usage, 4-44 
Program errors, E-5 



Program label, 7-1 

Programmatic execution of MPE commands, 4-9 

PTAPE intrinsic 

specifications, 2-169 

usage, 5-27 
PUTJCW intrinsic 

specifications, 2-170 

usage, 4-47 
PWRITE intrinsic, 2-171 



Queues, 95 
QUIT intrinsic 

specifications, 2-172 

usage, 4-20 
QUITPROG intrinsic 

specifications, 2-173 

usage, 4-22 
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Reading a file in direct -access mode, 10-49 
Reading a file in sequential order, 10-47 
Reading a user- defined file label 
on a labeled tape file, 10-89 

Reading input from $STDIN and $STDINX, 4-16 

Reading magnetic tape files, 3-70 

Reading paper tapes without X-OFF control, 5-27 

Reading the terminal input timer, 5-19 

Reading user file labels, 10-62 

READ intrinsic 

specifications, 2-174 

usage, 4-16 
READX intrinsic 

specifications, 2-175 

usage, 4-16 
Receiving mail, 7-12 
RECEIVEMAIL intrinsic 

specifications, 2-176 

usage, 7-12 
Record formats, 10-3 
Records, 10-2 
REJECT intrinsic, 2-178 
Relative I/O, 10-8 

Block format, 10-3 

FDELETE, 2-61 

FFILEINFO, 2-63 
Releasing global RIN's, 6-3 
REJECT intrinsic, 2-178 
Releasing global RIN's, 6-3 
Renaming a file, 10-44 
Requesting a process break, 4-17 
Requesting a reply from the Operator's Console, 4-18 
Required parameters, 1-8 
Rescheduling process, 7-13 
RESETCONTROL intrinsic 

specifications, 2-179 

usage, 4-40 

DEC 1981 



RESETDUMP intrinsic, 2-180 

Resetting the logical record pointer, 10-91 

Resource identification number, 6-1 

Resource management, 6-1 

Resources, 6-1 

Returns, intrinsic, 2-2 

RIN, 6-1 

Run-time errors, E-7 

Run-time messages, E-2 



Scheduling processes, 9-5 
Searching arrays, 4-3 
SEARCH intrinsic 

specifications, 2-181 

usage, 4-3 
Sectors, 10-2 
Segmenter driver, 7-6 
Segmenter subsystem, 7-6 
Segments 

activating, 8-10 

changing size of extra data segment, 8-15 

code segments, 8-1 

creating an extra data segment, 8-2 

data segment management capability, 8-1 

data segments, 8-1 

deleting, 8-15 

description, 8-1 

logical index number, 8-2 

stack segment, 8-1 

transferring data from extra data segment to stack, 8-15 

transferring data from stack to extra data segment, 8-15 
Sending mail, 7-11 
SENDMAIL intrinsic 

specifications, 2-182 

usage, 7-11 
Sequential access file reading, 10-47 
Sequential access file writing, 10-49 
Session main process, 7-1 

cT^rTTr»TTT\/rT> ;«4-«;«f.;« o 1 HA 

SETJCW intrinsic 

specifications, 2-185 

usage, 4-46 
Setting parity, 5-23 
Setting terminal type, 5-25 
Setting unedited terminal mode, 5-26 
Shared files, 10-16 
Son process, 7-3 

Source of file characteristics, 10-20 
Source of process activation, 7-14 
Spacing on disc or tape files, 10-89 
Special terminal keys, 5-8 
SPL 

calling intrinsics from, 1-2 

description, 1-1 
Split stack, 1-11, 2-3 
Spooling, 10-23 



Stack 

changing size, 4-22 

sizes, 4-22 

split stack, 1-11, 2-3 
STACKDUMP intrinsic, 2-170 
Stack segment, 8-1 
Standard traps, 4-31 
$STDIN, 10-9 
$STDINX, 10-10 
$STDLIST, 10-10 
Subqueues, 9-5 
Substates, 7-2 

Subsystem break function, 5-14 
Suggested Log File Uses, 3-98 
SUSPEND errors, E-l 3 
Suspending processes, 7-8 
SUSPEND intrinsic 

specifications, 2-188 

usage, 7-8 
Suspending the calling process, 4-19 
SWITCHDB intrinsic 

specifications, 2-189 

usage, 9-5 
System break function, 5-13 
System defined files, 10-9 
System file domain, 10-7 
System messages, 10-18, 10-19 
System procedures, 1-1 
Systems Programming Language 

calling intrinsics from, 1-2 

description, 1-1 
System timer, 4-42 
System traps, 4-35 



Tape density, determining, 10 -89b 

Tape label, writing, 10-84 

Tape labels, MPE, 10-75, D-l 

Tape-mode option, 5-15 

Temporarily privileged programs, 9-2 

Temporary files, 10-7 

Terminal and line printer carriage-control codes, 5-6 

Terminal input timer, 5-16 

Terminals, 5-8, 5-9 

Terminal speed, 5-10 

Terminating a process, 4-20 

TERMINATE intrinsic 

specifications, 2-190 

usage, 4-20 
Testing mailbox status, 7-10 
Time and data intrinsics, 4-42 
TIMER intrinsic 

specifications, 2-191 

usage 4-42 
Time outs, for IPC, 3-3, 3-8 
Transferring data from an extra data segment 
to the stack, 8-15 
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Transferring data from the stack to an 

extra data segment, 8-15 
Translating characters from EBCDIC to ASCII 

and ASCII to EBCDIC, 4-13 
Transmitting program input/output from job /session 

input/output devices, 4-16 
Traps 

arithmetic, 4-30 

commercial instruction, 4-32 

Control-Y, 4-38 

enabling and disabling, 4-29 

extended precision floating-point, 4-31 

library, 4-34 

standard, 4-31 

system, 4-35 
Types of files, 10-8 
Types of procedures, 2-2 



U 



Undefined length records, 10-3 
Unlabeled magnetic tape file, 10-77 

density selection, 10-89 
Unloading library procedures, 4-2 
UNLOADPROC intrinsic 

specifications, 2-192 

usage, 4-3 
UNLOCKGLORIN intrinsic 

specifications, 2-193 

usage, 6-3 
Unlocking files, 10-56 
Unlocking global RIN's, 6-3 
Unlocking lobal RIN's, 6-8 
UNLOCKLOCRIN intrinsic 

specifications, 2-194 

usage, 6-8 
Updating a file, 10-58 
Updating magnetic tape files, 10-75 
User block transfers, 5-22 
User-defined job control words, 4-47 
User file labels, 10-62 
User Logging Facility, 10-94 
User messages, E-18 
User pre-defined files, 10-10 
User processes, 7-2 
User's access mode, 4-10 
User's attributes, 4-10 
User's stack segment, 8-1 
Using disc space efficiently, 10-4 
Using FFILEINFO, 10-68 



Using FGETINFO, 10-66 

Using numeric values as parameters, 1-8 

Using the FCARD intrinsic 

to operate the HP 7 260 A Optical Mark Reader, 5-28 
Utility functions of intrinsics, 4-1 



Variable -length records, 10-3 
Virtual device directory, 10-15 
WHO intrinsic 

specifications, 2-195 

usage, 4-10 
Writer ID's, 3-3, 3-8 

Writing a file system error- check procedure, 10-46 
Writing a tape label, 10-84 
Writing on a magnetic tape file, 10-88 
Writing output to $STDLIST, 4-18 
Writing output to the Operator's Console, 4-18 
Writing records into a file in direct-access mode, 10-51 
Writing records into a file in sequential order, 10-49 
Writing to magnetic tape files, 10-77 
Writing user file labels, 10-62 
WRITELOG intrinsic 

specifications, 2-198 

usage, 10-94 



XARITRAP intrinsic 

specifications, 2-199 

usage, 4-32 
XCONTRAP intrinsic 

specifications, 2-201 

usage, 4-41 
XLIBTRAP intrinsic 

specifications, 2-202 

usage, 4-35 
X-OFF control, 5-21 
XSYSTRAP intrinsic 

specifications, 2-203 

usage, 4-36 



ZSIZE intrinsic 

specifications, 2-204 

usage, 4-27 
Z to DB area, 4-27 
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